Skip to main content

Your Vue app went white in production and your logs are empty. Here's why

Vue catches component errors before window.onerror sees them. How app.config.errorHandler, onErrorCaptured and Nuxt's hooks actually route errors, with code you can run.

Updated 8 min readMarkdown

A user sends a screenshot: a blank page where your checkout used to be. You open your error tracker. Nothing. You check the browser handler you wired to window.onerror. Nothing there either.

The reason is simple: Vue caught the error before the browser ever saw it. In a production build, Vue's default handler just logs it with console.error and moves on. No exception reaches window.onerror, so whatever listens there has nothing to report.

This post walks through where Vue 3 and Nuxt errors actually go, which ones Vue routes through its own handler, which ones it doesn't, and the small setup that covers both. The code is tool-agnostic; near the end we show how we wire it up in Telemetry Tracker.

What Vue does with an error, dev vs production

Vue wraps the code it calls for you: component renders, event handlers, lifecycle hooks, setup(), watchers, custom directive hooks and transition hooks. Errors thrown there are sent to app.config.errorHandler (Vue docs).

If you haven't set one, the default kicks in, and it behaves differently per mode. From the docs: the default handler re-throws errors during development and logs them during production. The throwUnhandledErrorInProduction docs spell out the trade-off: logging only "may prevent errors that only happen in production from being caught by error monitoring services."

That's the whole bug. In dev, you see a loud crash. In prod, you get a console.error on a user's machine that nobody will ever read.

You can see it in a few lines. We ran this against vue 3.5.45 in Node with jsdom and NODE_ENV=production:

// repro.cjs: npm i vue jsdom && NODE_ENV=production node repro.cjs
const { JSDOM } = require("jsdom");
const dom = new JSDOM('<div id="app"></div>');
Object.assign(global, { window: dom.window, document: dom.window.document,
  Element: dom.window.Element, SVGElement: dom.window.SVGElement });
const { createApp } = require("vue");

dom.window.onerror = (msg) => console.log("window.onerror:", msg); // never fires

const Checkout = { render() { throw new Error("price is undefined"); } };
createApp(Checkout).mount("#app");

console.log("DOM:", JSON.stringify(document.getElementById("app").innerHTML));

Output: Vue's console.error with the error, window.onerror silent, and the container left holding a single comment node (<!---->). That's your white screen.

Fix 1: set app.config.errorHandler before mounting

// main.ts
import { createApp } from "vue";
import App from "./App.vue";

const app = createApp(App);

app.config.errorHandler = (err, instance, info) => {
  // report it, e.g. send to your error tracker
  reportError(err, {
    component: instance?.$options?.name ?? instance?.$options?.__name,
    info,
  });
  console.error(err); // keep the console output you'd otherwise lose
};

app.mount("#app");

Three things worth knowing about the arguments:

  • err is unknown. People throw strings and plain objects too, so normalize before you read .stack.
  • instance is the component that triggered the error, or null.
  • info says where it came from. In production it's a shortened code, not the readable string. The Production Error Code Reference maps it: 1 is the render function, 3 a watcher callback, 5 a native event handler, m the mounted hook, and so on. In our 3.5.45 run, the value arrived as a link to that reference, e.g. https://vuejs.org/error-reference/#runtime-1. Store it as-is; it's the fastest clue to where in the component the error happened.

Setting your own errorHandler replaces the default, so if you don't log inside it, the console goes quiet too.

Async errors: what Vue routes, what it doesn't

This is where most setups leak. Running the same production build, we threw from each place and checked what reached errorHandler:

Where the error happens Reaches app.config.errorHandler?
Render function Yes (info code 1)
onMounted(() => { throw }) Yes (m)
onMounted(async () => { await …; throw }) Yes (m)
@click="async () => { await …; throw }" Yes (5)
watch(src, async () => { await …; throw }) Yes (3)
setTimeout(() => { throw }) inside a hook No, goes to the global uncaught error path
el.addEventListener("click", …) added by hand No, goes to window.onerror
fetchThing().then(() => { throw }) not returned or awaited No, goes to unhandled rejection

The rule of thumb: Vue handles what Vue calls, including a promise that a hook, handler or watcher callback returns. A timer callback, a listener you attached yourself, or a promise chain you fired and forgot runs outside Vue's call, so Vue never sees it.

So you need two layers, not one:

// The browser layer: everything Vue didn't call
window.addEventListener("error", (e) => reportError(e.error ?? e.message));
window.addEventListener("unhandledrejection", (e) => reportError(e.reason));

// The Vue layer: everything Vue did call
app.config.errorHandler = (err, instance, info) => { /* as above */ };

Most error-tracker SDKs install the browser layer for you. Check whether yours also hooks app.config.errorHandler, because that's the half that catches the white screens.

onErrorCaptured: local context, and one trap

onErrorCaptured (Composition API) and errorCaptured (Options API) run when an error propagates up from a descendant component (Vue docs). It's a good place to show a fallback UI for one part of the page:

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

const failed = ref(false);

onErrorCaptured((err, instance, info) => {
  failed.value = true; // render a fallback, NOT the content that just threw
  // no `return false`: let it reach app.config.errorHandler
});
</script>

<template>
  <p v-if="failed">This widget couldn't load. Try refreshing.</p>
  <slot v-else />
</template>

The propagation rules from the docs, in short:

  • By default, errors still go to app.config.errorHandler after your hook runs, so reporting stays in one place.
  • Several errorCaptured hooks up the parent chain all run, bottom to top.
  • If the hook itself throws, both errors go to app.config.errorHandler.
  • Returning false stops propagation: no further errorCaptured hooks, and no app.config.errorHandler for that error.

That last one is the trap. A boundary that returns false to "handle" the error also hides it from your reporter. We confirmed it in the same Node setup: with return false, the global handler never ran. If a boundary needs to stop propagation, report from inside it.

Also from the docs: in the fallback state, don't render the original content that caused the error, or the component goes into an infinite render loop.

Nuxt: vueApp, vue:error and app:error

Nuxt runs on the same Vue app, exposed as nuxtApp.vueApp. The Nuxt error-handling docs show both options in a plugin:

// app/plugins/errors.client.ts  (Nuxt 3: plugins/errors.client.ts)
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    // report to your service
  };

  // or: called if an error propagates up to the top level
  nuxtApp.hook("vue:error", (error, instance, info) => {
    // report to your service
  });
});

Per the Nuxt docs, vue:error is based on onErrorCaptured, and a separate app:error hook fires for startup errors: running plugins, processing the app:created/app:beforeMount/app:mounted hooks, and rendering to HTML during SSR. <NuxtErrorBoundary> stops client-side errors in its slot from bubbling to the top level, so if you use it, make sure its @error handler reports too.

On Nuxt 4, plugins live in app/plugins/. A file in a root plugins/ folder is ignored, and a silently ignored plugin looks exactly like "no errors."

How we do it in Telemetry Tracker

We build Telemetry Tracker, an open-source (MIT) error tracker for side projects and small teams. After init(), our browser SDK (@telemetry-tracker/core) registers window.onerror and unhandledrejection, which covers the browser layer. For the Vue layer, it's the same errorHandler pattern from above, with trackError doing the reporting:

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import { init, trackError } from "@telemetry-tracker/core";

init({
  ingestUrl: import.meta.env.VITE_TELEMETRY_INGEST_URL,
  app: "my-vue-app",
  apiKey: import.meta.env.VITE_TELEMETRY_API_KEY,
  platform: "web",
  environment: import.meta.env.MODE,
});

const app = createApp(App);
app.config.errorHandler = (err, instance, info) => {
  trackError(err, { source: "vue", vue_info: info });
  console.error(err); // keep the console log you'd otherwise lose
};
app.mount("#app");

On Nuxt, set the same handler on nuxtApp.vueApp.config.errorHandler in a client plugin.

Setup for both: Vue guide · Nuxt guide.

The checklist

  • app.config.errorHandler (or nuxtApp.vueApp.config.errorHandler) is set before mount().
  • It reports and still calls console.error.
  • info is stored with every report, and you know the production codes live in Vue's error reference.
  • window error and unhandledrejection listeners cover timers, manual listeners and fire-and-forget promises.
  • Async hooks, handlers and watchers return or await their promises, so Vue can route the rejection.
  • No onErrorCaptured returns false without reporting first.
  • Nuxt: plugin is in app/plugins/ on Nuxt 4, and app:error covers startup failures.
  • You broke a component on purpose in a production build and saw the report arrive.

That last box is the one that matters. Dev mode re-throws, so everything looks fine right up until it doesn't. Run vite build && vite preview, throw from a render function, and watch where the error lands.

No comments yet. Be the first to comment.