vue-debug-guides

Vue 3 debugging and error handling for runtime issues, warnings, async failures, and hydration bugs. For development best practices and common gotchas, use vue-best-practices.

Reactivity

• •Tracing unexpected re-renders and state updates → See reactivity-debugging-hooks

Watchers

• •Async operations overwriting with stale data → See watch-async-cleanup
• •Creating watchers inside async callbacks → See watch-async-creation-memory-leak

Components

• •Child component throws "component not found" error → See local-components-not-in-descendants
• •Click listener doesn't fire on custom component → See click-events-on-components
• •Parent can't access child ref data in script setup → See component-ref-requires-defineexpose
• •HTML template parsing breaks Vue component syntax → See in-dom-template-parsing-caveats
• •Wrong component renders due to naming collisions → See component-naming-conflicts
• •Parent styles don't apply to multi-root component → See multi-root-component-class-attrs

Props & Emits

• •Variables referenced in defineProps cause errors → See prop-defineprops-scope-limitation
• •Component emits undeclared event causing warnings → See declare-emits-for-documentation
• •defineEmits used inside function or conditional → See defineEmits-must-be-top-level
• •defineEmits has both type and runtime arguments → See defineEmits-no-runtime-and-type-mixed
• •Native event listeners not responding to clicks → See native-event-collision-with-emits
• •Component event fires twice when clicking → See undeclared-emits-double-firing

Templates

• •Getting template compilation errors with statements → See template-expressions-restrictions
• •"Cannot read property of undefined" runtime errors → See v-if-null-check-order
• •Dynamic directive arguments not working properly → See dynamic-argument-constraints
• •v-else elements rendering unconditionally always → See v-else-must-follow-v-if
• •Child components in loops showing undefined data → See v-for-component-props
• •Array order changing after sorting or reversing → See v-for-computed-reverse-sort
• •List items disappearing or swapping state unexpectedly → See v-for-key-attribute
• •Getting off-by-one errors with range iteration → See v-for-range-starts-at-one
• •v-show or v-else not working on template elements → See v-show-template-limitation

Template Refs

• •Ref becomes null when element is conditionally hidden → See template-ref-null-with-v-if
• •Ref array indices don't match data array in loops → See template-ref-v-for-order
• •Refactoring template ref names breaks silently in code → See use-template-ref-vue35

Forms & v-model

• •Initial form values not showing when using v-model → See v-model-ignores-html-attributes
• •Textarea content changes not updating the ref → See textarea-no-interpolation
• •iOS users cannot select dropdown first option → See select-initial-value-ios-bug
• •Parent and child components have different values → See define-model-default-value-sync
• •Object property changes not syncing to parent → See definemodel-object-mutation-no-emit
• •Real-time search/validation broken for Chinese/Japanese input → See v-model-ime-composition
• •Number input returns empty string instead of zero → See v-model-number-modifier-behavior
• •Custom checkbox values not submitted in forms → See checkbox-true-false-value-form-submission

Events & Modifiers

• •Chaining multiple event modifiers produces unexpected results → See event-modifier-order-matters
• •Keyboard shortcuts don't fire with system modifier keys → See keyup-modifier-timing

Lifecycle

• •Memory leaks from unremoved event listeners → See cleanup-side-effects
• •DOM access fails before component mounts → See lifecycle-dom-access-timing
• •DOM reads return stale values after state changes → See dom-update-timing-nexttick
• •SSR rendering differs from client hydration → See lifecycle-ssr-awareness

Slots

• •Wrapper components breaking child slot functionality → See slot-forwarding-to-child-components

Provide/Inject

• •Calling provide after async operations fails silently → See provide-inject-synchronous-setup
• •Tracing where provided values come from → See provide-inject-debugging-challenges
• •Injected values not updating when provider changes → See provide-inject-reactivity-not-automatic
• •Multiple components share same default object → See provide-inject-default-value-factory

Attrs

• •Both internal and fallthrough event handlers execute → See attrs-event-listener-merging
• •Explicit attributes overwritten by fallthrough values → See fallthrough-attrs-overwrite-vue3
• •Attributes applying to wrong element in wrappers → See inheritattrs-false-for-wrapper-components

Composables

• •Composable called outside setup context or asynchronously → See composable-call-location-restrictions
• •Composable reactive dependency not updating when input changes → See composable-tovalue-inside-watcheffect

Composition API

• •Lifecycle hooks failing silently after async operations → See composition-api-script-setup-async-context
• •Parent component refs unable to access exposed properties → See define-expose-before-await

Async Components

• •Network failures or timeouts loading components → See async-component-error-handling
• •Template refs undefined after component reactivation → See async-component-keepalive-ref-issue

Teleport

• •Teleport target element not found in DOM → See teleport-target-must-exist
• •Teleported content breaks SSR hydration → See teleport-ssr-hydration

Suspense

• •Need to handle async errors from Suspense components → See suspense-no-builtin-error-handling
• •Using Suspense with server-side rendering → See suspense-ssr-hydration-issues

SSR

• •HTML differs between server and client renders → See ssr-hydration-mismatch-causes

SFC (Single File Components)

• •Trying to use named exports from component script blocks → See sfc-named-exports-forbidden
• •Variables not updating in template after changes → See sfc-script-setup-reactivity

Plugins

• •Debugging why global properties cause naming conflicts → See plugin-global-properties-sparingly
• •Plugin not working or inject returns undefined → See plugin-install-before-mount

App Configuration

• •App configuration methods not working after mount call → See configure-app-before-mount