{"record":{"id":"dbbdcf3c14aae9a6","repo":"withastro/astro","slug":"unknowncompilererror","errorCode":"UnknownCompilerError","errorMessage":"${err.message ?? 'Unknown compiler error'}","messagePattern":"\\$\\{err\\.message \\?\\? 'Unknown compiler error'\\}","errorType":"exception","errorClass":"CompilerError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/compile/compile.ts","lineNumber":71,"sourceCode":"\t\t\t// TODO: remove in Astro v8\n\t\t\tastroGlobalArgs: JSON.stringify(astroConfig.site),\n\t\t\tscopedStyleStrategy: astroConfig.scopedStyleStrategy,\n\t\t\tresultScopedSlot: true,\n\t\t\ttransitionsAnimationURL: 'astro/components/viewtransitions.css',\n\t\t\tannotateSourceFile:\n\t\t\t\tviteConfig.command === 'serve' &&\n\t\t\t\tastroConfig.devToolbar &&\n\t\t\t\tastroConfig.devToolbar.enabled &&\n\t\t\t\ttoolbarEnabled,\n\t\t\tpreprocessedStyles,\n\t\t\tresolvePath(specifier) {\n\t\t\t\treturn resolvePath(specifier, filename);\n\t\t\t},\n\t\t});\n\t} catch (err: any) {\n\t\t// The compiler should be able to handle errors by itself, however\n\t\t// for the rare cases where it can't let's directly throw here with as much info as possible\n\t\tthrow new CompilerError({\n\t\t\t...AstroErrorData.UnknownCompilerError,\n\t\t\tmessage: err.message ?? 'Unknown compiler error',\n\t\t\tstack: err.stack,\n\t\t\tlocation: {\n\t\t\t\tfile: filename,\n\t\t\t},\n\t\t});\n\t}\n\n\thandleCompileResultErrors(filename, transformResult, cssTransformErrors);\n\n\treturn {\n\t\t...transformResult,\n\t\tcss: transformResult.css.map((code, i) => ({\n\t\t\t...cssPartialCompileResults[i],\n\t\t\tcode,\n\t\t})),\n\t};","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/withastro/astro/blob/3578d45d34226d63cff3d261c971c221de6794d2/packages/astro/src/core/compile/compile.ts#L53-L89","documentation":"`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.","triggerScenarios":"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.","commonSituations":"Partial upgrade leaving mixed astro/compiler versions; canary or nightly compiler builds; preprocessed styles producing intermediate input the compiler cannot handle; rare pathological syntax.","solutions":["Update `astro` and `@astrojs/compiler` together (`npm update astro @astrojs/compiler`) so versions stay in lockstep.","Remove any `overrides`/`resolutions` pinning `@astrojs/compiler` in package.json, then reinstall.","Isolate the file named in `location.file`, reduce it to a minimal repro, and comment out the offending block to unblock development.","If it reproduces on the latest versions, file an Astro issue with the stack and the minimized file."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const result = await compileFile(filename);\n} catch (err) {\n  if (err instanceof Error && err.name === 'UnknownCompilerError') {\n    // compiler crash, not user syntax — capture stack + file and report upstream\n    console.error({ file: filename, stack: err.stack });\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Upgrade `astro` and `@astrojs/compiler` together so their versions stay in lockstep.","Avoid `overrides`/`resolutions` that pin `@astrojs/compiler` to an unrelated version.","When reporting, minimize the file from the error's location before attaching it."],"tags":["compiler","internal","upgrade"],"backgroundTag":"compiler-crash","analyzedSha":"3578d45d34226d63cff3d261c971c221de6794d2","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}