{"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 v7\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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/compile/compile.ts#L53-L89","documentation":"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.","triggerScenarios":"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()`.","commonSituations":"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.","solutions":["Reinstall dependencies: delete `node_modules` and lockfile, then `npm install` to get a matching compiler.","Check the Node.js version matches Astro's `engines` requirement.","Update to the latest patch release of your Astro major version.","Isolate the offending `.astro` file (the error includes `location.file`) and simplify it to find the trigger, then report a bug if it reproduces."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await compile(...);\n} catch (e) {\n  if (e.code === 'UnknownCompilerError') { /* log + report; suggest reinstall */ }\n  else throw e;\n}","preventionTips":["Keep Node.js within Astro's supported version range.","Reinstall node_modules after major Astro upgrades.","Pin the compiler version via the lockfile to avoid drift."],"tags":["compiler","build","wasm","internal"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}