Diagnostics & Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• packages/nuxt/src/app/diagnostics/core.ts
• packages/kit/src/diagnostics/build.ts
• packages/nuxt/src/app/diagnostics/render.ts
• packages/kit/src/diagnostics/kit-api.ts
• packages/kit/src/diagnostics/config.ts
• packages/kit/src/diagnostics/pages.ts
• packages/kit/src/diagnostics/components.ts
• packages/kit/src/diagnostics/plugins.ts

Diagnostics and error handling in Nuxt provide a structured framework for identifying, reporting, and resolving issues across the build-time and runtime lifecycles. The system is built on the nostics engine, which categorizes issues into specific domains such as build, configuration, routing, and rendering. Each diagnostic entry includes a descriptive "why" (the cause of the issue) and a "fix" (the recommended action for the developer).

The framework distinguishes between build-time diagnostics (prefixed with NUXT_B), which guide developers through project setup and compilation, and runtime diagnostics (prefixed with NUXT_E), which handle errors occurring within the browser or during server-side rendering (SSR). This system ensures technical accuracy by strictly defining error codes and associated recovery paths.

Diagnostic Architecture and Classification

The diagnostics system is modularized by domain. Each module defines a set of unique codes that map to specific failure states. Build-time diagnostics are primarily managed within @nuxt/kit, while runtime diagnostics reside within the nuxt app core.

Diagnostic Flow

The following diagram illustrates how the diagnostic system intercepts issues during different phases of the application lifecycle.

The flow shows that issues detected during the configuration, module setup, or build phases generate NUXT_B codes for terminal reporting, while runtime rendering or lifecycle issues generate NUXT_E codes.
Sources: packages/kit/src/index.ts:51-58, packages/nuxt/src/app/diagnostics/core.ts:7-12

Domain Categorization

Code Range	Domain	Description
B1xxx	Build	Issues related to template compilation, file reading, and dependency installation.
B2xxx	Plugins	Parsing errors, circular dependencies, and invalid exports in Nuxt plugins.
B3xxx	Components	Component discovery, hydration strategy conflicts, and island detection.
B4xxx	Pages/Routing	Route collisions, invalid definePageMeta calls, and layout resolution issues.
B5xxx	Configuration	Missing compatibilityDate, schema loading errors, and invalid webpack targets.
B8xxx	Kit API	Contextual errors when calling Nuxt Kit utilities outside supported functions.
E1xxx	App Core	Lifecycle runtime errors, improper composable usage, and SSR header conflicts.
E4xxx	Rendering	Layout root node errors, hydration mismatches, and island response failures.

Sources: packages/kit/src/diagnostics/build.ts:8-13, packages/kit/src/diagnostics/plugins.ts:8-13, packages/kit/src/diagnostics/pages.ts:8-13, packages/nuxt/src/app/diagnostics/render.ts:8-11

Build-Time Diagnostics (NUXT_B)

Build-time diagnostics are critical for ensuring the integrity of the project structure before deployment. They utilize a nostics reporter to provide actionable feedback in the development terminal.

Template and Build Logic (B1xxx)

The build system monitors template compilation (e.g., addTemplate). If a template fails to compile due to syntax errors in getContents or a missing src path, the system reports NUXT_B1001 or NUXT_B1003.
Sources: packages/kit/src/diagnostics/build.ts:16-29

Configuration and Kit API (B5xxx / B8xxx)

The configuration engine enforces strict rules, such as reserving the app namespace in runtimeConfig (NUXT_B5003). The Kit API diagnostics ensure that utilities like useNuxt() or useNitro() are called within the correct context, such as a module setup() or a nuxt.hook() callback (NUXT_B8001, NUXT_B8003).
Sources: packages/kit/src/diagnostics/config.ts:22-25, packages/kit/src/diagnostics/kit-api.ts:14-25

Plugin Analysis (B2xxx)

Nuxt performs static analysis on plugins to optimize the runtime bundle. Diagnostics are triggered for:

• Circular Dependencies: NUXT_B2009 reports cycles in the dependsOn array.
• Static Meta Parsing: NUXT_B2010 warns if static properties cannot be parsed from defineNuxtPlugin.
  Sources: packages/kit/src/diagnostics/plugins.ts:50-59

Runtime Diagnostics (NUXT_E)

Runtime diagnostics occur during application execution. These are split into production-safe and development-only variants to minimize overhead while maintaining debuggability.

Core Lifecycle Diagnostics (E1xxx)

Nuxt monitors the execution context of composables. If a composable requiring the Nuxt instance is called outside of a supported lifecycle (like setup() or a plugin), NUXT_E1001 is thrown.
Sources: packages/nuxt/src/app/diagnostics/core.ts:14-17

Rendering and Islands (E4xxx)

The rendering engine enforces structural requirements for components and layouts. A frequent diagnostic is the "Single Root Node" requirement:

• Layouts: NUXT_E4002 warns if a layout template lacks a single root node.
• Pages: NUXT_E4004 warns if a page component lacks a single root node.
• Islands: NUXT_E4005 enforces single root elements for server-only components.

The sequence diagram demonstrates the structural validation performed during the rendering process. If multiple root nodes are detected, the system issues a warning as it compromises route transition stability.
Sources: packages/nuxt/src/app/diagnostics/render.ts:19-35

Diagnostic Reporting Structure

Each diagnostic entry is defined with specific properties to ensure consistency and utility for the developer.

// Example Diagnostic Entry Structure
NUXT_B4003: {
  why: (p: { callCount: number, file: string }) => 
    `definePageMeta() is called ${p.callCount} times in ${p.file}, but only one call is allowed.`,
  fix: 'Merge all definePageMeta() calls into a single call.',
  docs: false,
}

• why: A string or a function returning a string that describes the error. It often includes parameters (like file paths or count values) to provide specific context.
• fix: A string describing the exact steps needed to resolve the diagnostic.
• docs: A boolean or string. If false, no external documentation link is generated. If true or a string, it links to the base documentation URL defined in the diagnostic catalog.

Sources: packages/kit/src/diagnostics/pages.ts:24-28, packages/kit/src/diagnostics/kit-api.ts:8-13

Error Boundaries and Fallbacks

Nuxt provides mechanisms to contain runtime errors within specific parts of the UI.

• NuxtErrorBoundary: A component that captures errors from its children.
• NuxtClientFallback: If SSR rendering fails inside this component, it triggers NUXT_E4006 and falls back to client-side rendering to maintain application availability.
  Sources: packages/nuxt/src/app/diagnostics/render.ts:40-43

Summary

The Nuxt Diagnostics & Error Handling system provides a robust layer of safety and developer guidance. By categorizing issues into build-time (NUXT_B) and runtime (NUXT_E) domains, it allows developers to intercept and fix structural, configuration, and rendering issues early. The integration with the nostics engine ensures that every reported issue is accompanied by a concrete fix, reducing debugging time and improving overall application stability.