withastro/astro · error · CompilerError

CompilerError

CompilerError

Error message

${compilerError.text}

What it means

Unlike the catch-all `UnknownCompilerError`, this is a structured compiler diagnostic: the compiler returned a `TransformResult` whose `diagnostics` array contains an entry with `severity === 'error'`. The wrapper promotes it into a `CompilerError` with line/column/file/hint extracted from the diagnostic's first label. This is the normal path for syntax errors and template validation failures in `.astro` files.

Source

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

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

function handleCompileResultErrors(
	filename: string,
	result: TransformResult,
	cssTransformErrors: AstroError[],
) {
	const compilerError = result.diagnostics.find((diag) => diag.severity === 'error');

	if (compilerError) {
		throw new CompilerError({
			name: 'CompilerError',
			message: compilerError.text,
			location: {
				line: compilerError.labels[0].line,
				column: compilerError.labels[0].column,
				file: filename,
			},
			hint: compilerError.hint,
		});
	}

	switch (cssTransformErrors.length) {
		case 0:
			break;
		case 1: {
			throw cssTransformErrors[0];
		}
		default: {

View on GitHub (pinned to d081033d5f)

Solutions

1. Read the reported line/column in the `.astro` file and fix the syntax error.
2. Use the diagnostic's `hint` field for suggested fixes.
3. Run `astro check` for additional TypeScript/diagnostics context.
4. If the message is unclear, comment out the flagged region and re-add incrementally to isolate the construct.

try {
  await astroBuild();
} catch (e) {
  if (e.name === 'CompilerError') { /* show e.location, e.hint */ } else throw e;
}

When it happens

Trigger: Authoring a `.astro` file with invalid frontmatter syntax, mismatched JSX-like tags in the template, an unclosed code fence, or disallowed constructs the compiler explicitly rejects.

Common situations: Typos in the template (unclosed tags, invalid directive syntax); frontmatter JavaScript syntax errors; using compiler features incorrectly (e.g., malformed `set:html`); copy-paste introducing stray characters.

Related errors

• UnknownCompilerError
• ${cssTransformErrors[0].message}
• [RSS] You can only glob entries within 'src/pages/' when pas
• [astro:actions] `defineAction()` unexpectedly used on the cl
• [astro:actions] `getActionContext()` unexpectedly used on th

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