{"record":{"id":"33c1481d4cad033d","repo":"anomalyco/sst","slug":"build-metadata-file-not-found-at-filepath-up","errorCode":null,"errorMessage":"Build metadata file not found at \"${filePath}\". Update your \"astro-sst\" adapter and rebuild your Astro site.","messagePattern":"Build metadata file not found at \"(.+?)\"\\. Update your \"astro-sst\" adapter and rebuild your Astro site\\.","errorType":"exception","errorClass":"VisibleError","httpStatus":null,"severity":"error","filePath":"platform/src/components/aws/astro.ts","lineNumber":413,"sourceCode":" * ```\n */\nexport class Astro extends SsrSite {\n  constructor(\n    name: string,\n    args: AstroArgs = {},\n    opts: ComponentResourceOptions = {},\n  ) {\n    super(__pulumiType, name, args, opts);\n  }\n\n  protected normalizeBuildCommand() { }\n\n  protected buildPlan(outputPath: Output<string>): Output<Plan> {\n    return outputPath.apply((outputPath) => {\n      const BUILD_META_FILE_NAME = \"sst.buildMeta.json\";\n      const filePath = path.join(outputPath, \"dist\", BUILD_META_FILE_NAME);\n      if (!fs.existsSync(filePath)) {\n        throw new VisibleError(\n          `Build metadata file not found at \"${filePath}\". Update your \"astro-sst\" adapter and rebuild your Astro site.`,\n        );\n      }\n      const buildMeta = JSON.parse(fs.readFileSync(filePath, \"utf-8\")) as {\n        base: string;\n        pluginVersion: string;\n        outputMode: \"server\" | \"static\";\n        responseMode: \"stream\" | \"buffer\";\n        clientBuildOutputDir: string;\n        clientBuildVersionedSubDir: string;\n      };\n      const serverOutputPath = path.join(outputPath, \"dist\", \"server\");\n\n      if (\n        buildMeta.pluginVersion === undefined ||\n        isALtB(buildMeta.pluginVersion, \"3.1.2\")\n      ) {\n        throw new VisibleError(","sourceCodeStart":395,"sourceCodeEnd":431,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/platform/src/components/aws/astro.ts#L395-L431","documentation":"The Astro component inspects the output of your `astro build` to plan routes (server vs static). The `astro-sst` adapter writes `dist/sst.buildMeta.json` during the build; if it's absent, SST cannot read route metadata and throws, instructing you to update/rebuild with the adapter in place.","triggerScenarios":"Deploying `sst.aws.Astro` where `buildCommand` output (site output path)/dist lacks `sst.buildMeta.json` — typically because the site was built without the `astro-sst` adapter installed or configured in `astro.config.mjs`, or with a stale/dist build output.","commonSituations":"Adding the SST component to an existing Astro app whose dist folder predates the adapter; forgetting to add `astroSst()` to `astro.config.mjs` integrations; CI caching an old build artifact; custom `buildCommand` that bypasses the adapter's hooks.","solutions":["Install the adapter: `npm install astro-sst`, and register it in `astro.config.mjs` integrations (`astroSst()`), then rebuild (`npm run build`) and redeploy","Delete stale build output (dist/.sst etc.) and rebuild so the adapter regenerates sst.buildMeta.json","If using a custom `buildCommand`/`installCommand` in the sst.config, ensure it runs the standard astro build with the adapter loaded","Update the astro-sst adapter to the latest version compatible with your SST version"],"exampleFix":"// before (astro.config.mjs)\nexport default defineConfig({ integrations: [] });\n// after\nimport astroSst from \"astro-sst\";\nexport default defineConfig({ integrations: [astroSst()], output: \"server\" });","handlingStrategy":"validation","validationCode":"import fs from \"fs\";\nimport path from \"path\";\nconst metaPath = path.join(siteOutputPath, \"dist\", \"sst.buildMeta.json\");\nif (!fs.existsSync(metaPath))\n  throw new Error(\"sst.buildMeta.json missing — install/configure the astro-sst adapter and rebuild before sst deploy\");","typeGuard":"function hasBuildMeta(outputPath) {\n  return fs.existsSync(path.join(outputPath, \"dist\", \"sst.buildMeta.json\"));\n}","tryCatchPattern":"try {\n  plan = buildPlan(outputPath);\n} catch (e) {\n  if (String(e).includes(\"Build metadata file not found\")) {\n    execSync(\"npm run build\"); // rebuild with adapter\n    plan = buildPlan(outputPath);\n  } else throw e;\n}","preventionTips":["Register astroSst() in astro.config.mjs integrations before building","Do a clean rebuild (rm -rf dist node_modules/.astro) when switching SST or adapter versions","In CI, verify sst.buildMeta.json exists after the build step and before deploy","Avoid custom buildCommand overrides that skip adapter hooks"],"tags":["astro","build","adapter","missing-file"],"backgroundTag":"build-artifact-missing","analyzedSha":"a0bd20f762883e72a35caccb4896c42ce5b3f707","analyzedAt":"2026-08-30T11:26:00.383Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}