withastro/astro · error · CompilerError

CompilerError

CompilerError

Error message

${compilerError.text}

What it means

`CompilerError` surfaces when the Astro compiler reports a diagnostic with severity `error` for a `.astro` file. The first error diagnostic is rethrown with its exact line/column (from the diagnostic's first label), the file, and the compiler's `hint` text. This is the normal channel for `.astro` syntax errors.

Solutions

1. Open the file and line/column reported in the error and fix the syntax.
2. Read the `hint` field — the compiler often states exactly what is malformed.
3. Comment out recently changed template blocks to narrow the location if the span is wide.
4. Check the Astro docs for the directive/component syntax you were writing.

Example fix

<!-- before: src/pages/index.astro -->
<h1>{title</h1>

<!-- after -->
<h1>{title}</h1>

# Catch component syntax errors before they surface in a build
npx astro check

try {
  await buildPage(file);
} catch (err) {
  if (err instanceof Error && err.name === 'CompilerError') {
    showDiagnostic(err.message, err.loc?.file, err.loc?.line, err.loc?.column, err.hint);
    return;
  }
  throw err;
}

When it happens

Trigger: A syntax error in an `.astro` file's frontmatter or template: unclosed tags, malformed expressions, invalid directive usage — anything the compiler flags at severity `error` while transforming that file.

Common situations: Typo in a template expression (`{title` without `}`), mismatched/unclosed component tags, invalid frontmatter JavaScript, using a directive with wrong arguments.

Related errors

• NoMatchingImport
• Unexpected template-exit instruction without a matching…
• UnknownCompilerError

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

Appendix: 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 3578d45d34)