Error handling

Astro takes errors seriously: every error has a code, a title, a message function, and a hint. The dev overlay renders them as polished, copy-pasteable cards.

Purpose

Catch errors thrown anywhere in the framework, classify them, and present them with maximum signal — both to the user (in a browser overlay) and in CI logs.

Key files

File	Purpose
packages/astro/src/core/errors/errors-data.ts	Declarative table of every error code. 2,261 lines — second-largest single file in the repo.
packages/astro/src/core/errors/errors.ts	AstroError, AggregateError, CompilerError, MarkdownError, CSSError.
packages/astro/src/core/errors/userError.ts	AstroUserError — exposed via astro/errors for integration authors.
packages/astro/src/core/errors/utils.ts	Stack-trace cleanup, source-mapping, error wrapping.
packages/astro/src/core/errors/zod-error-map.ts	Friendly Zod error messages for config and content schemas.
packages/astro/src/core/errors/printer.ts	CLI/CI output formatting.
packages/astro/src/core/errors/overlay.ts	Server-side payload that the dev overlay renders.
packages/astro/src/core/errors/dev/	Dev overlay glue.
packages/astro/src/vite-plugin-overlay/	Vite plugin that mounts the overlay in the browser.
packages/astro/src/runtime/client/dev-overlay.ts	Browser-side overlay UI.

Anatomy of an error definition

// errors-data.ts
export const InvalidImageService = {
  name: 'InvalidImageService',
  title: 'Failed to load image service.',
  message: () =>
    `There was an error loading the configured image service. Please see the stack trace for more information.`,
  hint: 'There may be more information in the terminal console. If you reported this error, please include all of these details so we can help.',
  code: 3007,
} satisfies ErrorData;

Each entry is then thrown as:

throw new AstroError(InvalidImageService);

AstroError carries the data forward to the overlay and CLI printers without lossy stringification.

Lifecycle of an error

graph TD
    A[Throw site] --> B[AstroError or wrapped error]
    B --> C{Where caught?}
    C -- Vite plugin --> D[overlay.ts → vite error]
    C -- RenderContext --> E[error route resolution]
    E --> F[404/500 designed page]
    C -- CLI command --> G[throw-and-exit.ts → printer.ts]
    D --> H[Dev overlay UI]
    G --> I[CI log]
    F --> J[Browser]

packages/astro/src/cli/throw-and-exit.ts is the last line of defense for CLI commands — it prints a structured trace and chooses the exit code.

Dev overlay

The overlay is a small custom-element UI (packages/astro/src/runtime/client/dev-overlay.ts) that renders the error payload, source-map context, hint, and a "report this" link. It is mounted on every dev page by vite-plugin-overlay.

The overlay also surfaces errors emitted from outside the request lifecycle (config errors, integration errors, build-only errors thrown during HMR re-evaluation).

User errors

Integrations should throw AstroUserError (from astro/errors) for problems that are the user's fault (misconfiguration, missing dependency). The CLI/printer treats user errors specially:

• No stack trace by default.
• --verbose reveals the trace.
• The exit code remains non-zero.

Zod error formatting

zod-error-map.ts registers a custom Zod error map that produces friendlier messages for content schemas and astro config validation. A user editing astro.config.mjs and getting a ZodError benefits from this directly.

Adding a new error

1. Append a new entry to errors-data.ts with a unique numeric code. (Codes are ranges per subsystem — search for "Compiler error" / "CSS error" / etc. headers.)
2. Throw new AstroError(MyNewError, optionalParams) from your code.
3. Tests in packages/astro/test/errors/ should cover the case.

Entry points for modification

• Change overlay UI: runtime/client/dev-overlay.ts.
• Change CLI formatting: core/errors/printer.ts.
• Add a new error class (rare): core/errors/errors.ts.

Related pages

• how-to-contribute / debugging
• how-to-contribute / patterns and conventions