withastro/astro · error · CompilerError

UnknownCompilerError

UnknownCompilerError

Error message

${err.message ?? 'Unknown compiler error'}

What it means

`UnknownCompilerError` is a safety net in `transform()` (compile.ts): normally the Astro compiler reports problems as diagnostics, but if calling the compiler itself throws, Astro wraps the raw exception, preserving its message and stack and adding the file being compiled. It signals a compiler crash, not a mistake in your code.

Solutions

  1. Update `astro` and `@astrojs/compiler` together (`npm update astro @astrojs/compiler`) so versions stay in lockstep.
  2. Remove any `overrides`/`resolutions` pinning `@astrojs/compiler` in package.json, then reinstall.
  3. Isolate the file named in `location.file`, reduce it to a minimal repro, and comment out the offending block to unblock development.
  4. If it reproduces on the latest versions, file an Astro issue with the stack and the minimized file.
Defensive patterns

Strategy: try-catch

Try / catch

try {
  const result = await compileFile(filename);
} catch (err) {
  if (err instanceof Error && err.name === 'UnknownCompilerError') {
    // compiler crash, not user syntax — capture stack + file and report upstream
    console.error({ file: filename, stack: err.stack });
    process.exit(1);
  }
  throw err;
}

Prevention

When it happens

Trigger: The `@astrojs/compiler` transform throwing on a specific `.astro` file — typically version skew between `astro` and `@astrojs/compiler` (package.json overrides pinning an old compiler), or an edge-case file (frontmatter/template after preprocessing, injected styles) that crashes the transform.

Common situations: Partial upgrade leaving mixed astro/compiler versions; canary or nightly compiler builds; preprocessed styles producing intermediate input the compiler cannot handle; rare pathological syntax.

Related errors

AI-assisted analysis of withastro/astro@3578d45d34 (2026-08-18). Data as JSON: /api/errors/dbbdcf3c14aae9a6. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/compile/compile.ts:71

			// TODO: remove in Astro v8
			astroGlobalArgs: JSON.stringify(astroConfig.site),
			scopedStyleStrategy: astroConfig.scopedStyleStrategy,
			resultScopedSlot: true,
			transitionsAnimationURL: 'astro/components/viewtransitions.css',
			annotateSourceFile:
				viteConfig.command === 'serve' &&
				astroConfig.devToolbar &&
				astroConfig.devToolbar.enabled &&
				toolbarEnabled,
			preprocessedStyles,
			resolvePath(specifier) {
				return resolvePath(specifier, filename);
			},
		});
	} catch (err: any) {
		// The compiler should be able to handle errors by itself, however
		// for the rare cases where it can't let's directly throw here with as much info as possible
		throw new CompilerError({
			...AstroErrorData.UnknownCompilerError,
			message: err.message ?? 'Unknown compiler error',
			stack: err.stack,
			location: {
				file: filename,
			},
		});
	}

	handleCompileResultErrors(filename, transformResult, cssTransformErrors);

	return {
		...transformResult,
		css: transformResult.css.map((code, i) => ({
			...cssPartialCompileResults[i],
			code,
		})),
	};

View on GitHub (pinned to 3578d45d34)