withastro/astro · error · CompilerError

UnknownCompilerError

UnknownCompilerError

Error message

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

What it means

The Astro compiler (`@astrojs/compiler`) transforms `.astro` files; if it throws an unexpected exception outside its own diagnostic system, the wrapper at `compile.ts:71` catches it and re-throws as `UnknownCompilerError` with the original message and stack. This is a catch-all for compiler bugs or environment failures (WASM load, panic) that the compiler did not surface as a structured diagnostic.

Source

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

			// TODO: remove in Astro v7
			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 d081033d5f)

Solutions

1. Reinstall dependencies: delete `node_modules` and lockfile, then `npm install` to get a matching compiler.
2. Check the Node.js version matches Astro's `engines` requirement.
3. Update to the latest patch release of your Astro major version.
4. Isolate the offending `.astro` file (the error includes `location.file`) and simplify it to find the trigger, then report a bug if it reproduces.

try {
  await compile(...);
} catch (e) {
  if (e.code === 'UnknownCompilerError') { /* log + report; suggest reinstall */ }
  else throw e;
}

When it happens

Trigger: The compiler WASM binary fails to load or panics; an unsupported syntax edge case crashes the compiler; a corrupted `.astro` file triggers an internal assertion; platform incompatibility (e.g., wrong WASM target) during `compile()`.

Common situations: Upgrading Astro across a major version where the compiler binding is stale; Node version mismatch with the compiler's WASM requirements; a malformed `.astro` file with unusual character sequences; corrupted `node_modules` after a botched install.

Related errors

• CompilerError
• ${cssTransformErrors[0].message}
• This is an error caused by Astro and not your code. Please f
• [RSS] You can only glob entries within 'src/pages/' when pas
• [astro:actions] `defineAction()` unexpectedly used on the cl

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