Harnessing Vue’s onErrorCaptured Lifecycle Hook for Robust Error Handling

When building complex single-page applications, unhandled runtime errors can quickly snowball into broken user experiences and difficult debugging sessions. Vue 3 ships with a powerful—but often overlooked—tool to intercept those exceptions close to where they happen: the onErrorCaptured lifecycle hook.

In this post we’ll explore what onErrorCaptured does, when it fires, and practical patterns for logging, recovering, and testing error states in your Vue components.

What exactly is onErrorCaptured?

onErrorCaptured is a composition-API variant of the Options-API errorCaptured option.

It lets a component listen for uncaught errors propagated from its child component tree (including async errors thrown in setup, lifecycle hooks, watchers, template event handlers, etc.).

import { defineComponent, onErrorCaptured } from 'vue';

export default defineComponent({
  setup() {
    onErrorCaptured((err, instance, info) => {
      // 1. err      → the Error (or thrown value)
      // 2. instance → the component instance where it originated
      // 3. info     → string describing the execution context
      console.error('[UI error]', info, err);
      // return false to stop further propagation
    });
  },
});

If your callback returns false, Vue halts the bubbling process—preventing ancestor components (and the global app handler) from seeing the same error. Otherwise, the error continues upward until handled or logged by Vue’s global error handler.

Execution Timing & Scope

State / Scope	Will onErrorCaptured Fire?	Notes
Child’s setup() / lifecycle hooks	✔️	Sync & async
Template event handlers (@click)	✔️	Even inside v-if branches
Watchers / computed getters	✔️	Both deep & immediate
Parent’s own code	❌	Hook only sees descendant errors

If you need to catch this component’s own errors, attach a global handler or wrap risky logic in local try / catch blocks.

A practical example—graceful fallback UI

<script setup lang="ts">
import { ref, onErrorCaptured } from 'vue';
import RiskyWidget from './RiskyWidget.vue';

const hasError = ref(false);

onErrorCaptured((err) => {
  hasError.value = true;
  // forward to a logging service
  reportToSentry(err);
  // stop propagation so parent doesn’t also render its error state
  return false;
});
</script>

<template>
  <RiskyWidget v-if="!hasError" />
  <ErrorBanner v-else message="Something went wrong loading the widget." />
</template>

Why this works

• The wrapper component doesn’t care where in RiskyWidget the exception arose—it just flips to a fallback UI.
• By returning false, you ensure the error is “handled” here, avoiding duplicate toasts higher up.

Integrating with global error tracking

Most teams pair local capture with an app-level handler registered via app.config.errorHandler. Use onErrorCaptured to supplement it with contextual recovery:

import { createApp } from 'vue';
import * as Sentry from '@sentry/vue';

const app = createApp(App);

app.config.errorHandler = (err, vm, info) => {
  Sentry.captureException(err, { extra: { info } });
};

At component level you might still:

• Provide user-friendly fallback UI
• Roll back optimistic updates
• Retry background requests

Testing error flows

Using Vitest (or Jest) you can assert that your component gracefully handles failures:

it('renders fallback on child error', async () => {
  vi.spyOn(console, 'error').mockImplementation(() => {});
  const wrapper = mount(Wrapper);

  // Force the child to throw
  wrapper.findComponent(RiskyWidget).vm.$emit('error', new Error('Boom'));

  await nextTick();
  expect(wrapper.text()).toContain('Something went wrong');
});

Remember to mock out console errors to keep test output tidy.

Common pitfalls & best practices

Pitfall	Fix
Swallowing errors without logging—makes debugging production issues impossible.	Always log or report the error before returning false.
Returning non-boolean values—Vue treats anything but false as “continue bubbling”	Explicitly return false when you truly handled it.
Expecting to catch top-level await/Promise rejections not originating from a component context.	Handle those in a global listener (window.addEventListener(‘unhandledrejection’, …)) or your network layer.

When to rely on onErrorCaptured vs. global handlers

Use onErrorCaptured when you want localized recovery or specialized logging (e.g., include feature flags, route params, or user actions leading up to the error).

Use the global handler for application-wide concerns—sending telemetry, showing a generic crash overlay, or refreshing the app after a fatal error.

Closing Thoughts

onErrorCaptured empowers Vue developers to create resilient components that can fail softly, showing friendly fallbacks instead of white screens and console spew. Coupled with a global error handler, it forms a robust strategy to surface, log, and recover from runtime problems—keeping your users happy and your debugging sessions short.

Next time you integrate a third-party widget or roll out a risky refactor, wrap it with a small component and tap into onErrorCaptured. Your future self (and your users) will thank you.