withastro/astro

Debugging

Pointers for the most common failure modes you will encounter while developing on Astro. Most of the deepest knowledge in this codebase has accumulated as a set of empirical "if you see X, look at Y" lookups — this page collects them.

Vite verbose logs

Vite is the underlying engine for both astro dev and astro build. Setting DEBUG=vite:* produces an extremely detailed trace.

DEBUG=vite:* astro dev
DEBUG=vite:deps astro dev      # dep optimizer (most common pain point)
DEBUG=vite:transform astro dev # show every transform
DEBUG=vite:hmr astro dev
DEBUG=vite:resolve astro dev

"`require is not defined`" in `astro dev` only

This almost always means Vite's dep optimizer failed to pre-bundle a CommonJS dependency. astro build uses Rollup which handles CJS→ESM reliably; astro dev uses esbuild's optimizer scan, which is intentionally shallow and misses dependencies that are only reachable through non-JS files (like .astro components in node_modules).

Files to inspect:

packages/astro/src/vite-plugin-environment/index.ts — sets optimizeDeps.entries.
packages/astro/src/core/create-vite.ts — wires up vitefu and crawlFrameworkPkgs.

The full debugging playbook is in reference / Vite dep optimizer, mirrored from the deep dive in AGENTS.md.

Dev overlay errors

When the dev server catches an error, it forwards a structured error to the browser overlay. Implementation:

packages/astro/src/core/errors/dev/ — server-side rendering of the overlay payload.
packages/astro/src/vite-plugin-overlay/ — Vite plugin that mounts the overlay in dev.
packages/astro/src/runtime/client/dev-overlay.ts — browser-side overlay UI.

Errors are defined in packages/astro/src/core/errors/errors-data.ts. Each entry has a code, title, message function, and hint. Search this file by error code before adding a new entry.

Hot module reload weirdness

If client:* components stop updating after a save:

Verify the file extension matches the framework integration. client:only="react" requires the React renderer to be configured.
Check packages/astro/src/vite-plugin-hmr-reload/ for the full-page reload trigger logic.
Use agent-browser (or any real browser) — curl cannot exercise HMR, since the protocol is WebSocket.
Logs: pnpm exec bgproc logs -n devserver.

Routing surprises

The route manifest is built up by:

packages/astro/src/core/routing/router.ts — createRouteManifest() walks src/pages/ and produces RouteData[].
packages/astro/src/core/routing/match.ts — request URL → RouteData matcher (sorted by priority).
packages/astro/src/core/routing/priority.ts — disambiguates between overlapping dynamic segments.

If a request 404s in dev but works in prod (or vice versa), the most common cause is a prerender flag mismatch. Check packages/astro/src/core/routing/prerender.ts.

`astro build` that 404s in production

Adapter problems usually show up here.

packages/astro/src/core/app/manifest.ts builds the SSRManifest.
packages/astro/src/core/app/base.ts is the App class adapters wrap.
The adapter (e.g. packages/integrations/node/src/preview.ts) consumes the manifest. If its req → AppRequest translation drops headers or the URL pathname, you'll see misroutes.

Check validate-headers.ts in core/app/ for the header allow/deny lists.

Content collections type drift

If astro:content types are stale:

Run pnpm -C <example> astro sync. This is what the IDE invokes after touching src/content/.
The generator lives in packages/astro/src/content/types-generator.ts (the largest single content file at 2,031 lines).
The watcher that triggers regeneration is packages/astro/src/content/watcher.ts.

Logging

Public API: astro/logger, astro/logger/node, astro/logger/json, astro/logger/console.

Internally packages/astro/src/core/logger/core.ts defines AstroLogger. Use logger.warn('SKIP_FORMAT', message) to bypass label formatting (used when piping pre-formatted strings such as version banners).

In integrations, the per-integration logger is provided as AstroIntegrationLogger and prefixes all output with the integration name. Public type: astro/types/AstroIntegrationLogger.

Common error families

Error code	Meaning	Look at
`MissingMediaQueryDirective`	`client:media` without a query	`packages/astro/src/runtime/client/media.ts`
`NoMatchingRenderer`	A framework component had no renderer	`packages/astro/src/vite-plugin-renderers/`
`InvalidComponentArgs`	Calling an Astro component without props	`packages/astro/src/runtime/server/render/component.ts`
`UnknownContentCollection`	`getCollection()` for an undeclared collection	`packages/astro/src/content/utils.ts`
`InvalidImageService`	`image.service` config could not load	`packages/astro/src/assets/services/`

The full list (codes, titles, hints) is in packages/astro/src/core/errors/errors-data.ts.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.