anomalyco/sst · error · VisibleError

Build metadata file not found at "${filePath}". Update your

Error message

Build metadata file not found at "${filePath}". Update your "astro-sst" adapter and rebuild your Astro site.

What it means

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.

Source

Thrown at platform/src/components/aws/astro.ts:413

 * ```
 */
export class Astro extends SsrSite {
  constructor(
    name: string,
    args: AstroArgs = {},
    opts: ComponentResourceOptions = {},
  ) {
    super(__pulumiType, name, args, opts);
  }

  protected normalizeBuildCommand() { }

  protected buildPlan(outputPath: Output<string>): Output<Plan> {
    return outputPath.apply((outputPath) => {
      const BUILD_META_FILE_NAME = "sst.buildMeta.json";
      const filePath = path.join(outputPath, "dist", BUILD_META_FILE_NAME);
      if (!fs.existsSync(filePath)) {
        throw new VisibleError(
          `Build metadata file not found at "${filePath}". Update your "astro-sst" adapter and rebuild your Astro site.`,
        );
      }
      const buildMeta = JSON.parse(fs.readFileSync(filePath, "utf-8")) as {
        base: string;
        pluginVersion: string;
        outputMode: "server" | "static";
        responseMode: "stream" | "buffer";
        clientBuildOutputDir: string;
        clientBuildVersionedSubDir: string;
      };
      const serverOutputPath = path.join(outputPath, "dist", "server");

      if (
        buildMeta.pluginVersion === undefined ||
        isALtB(buildMeta.pluginVersion, "3.1.2")
      ) {
        throw new VisibleError(

View on GitHub (pinned to a0bd20f762)

Solutions

1. Install the adapter: `npm install astro-sst`, and register it in `astro.config.mjs` integrations (`astroSst()`), then rebuild (`npm run build`) and redeploy
2. Delete stale build output (dist/.sst etc.) and rebuild so the adapter regenerates sst.buildMeta.json
3. If using a custom `buildCommand`/`installCommand` in the sst.config, ensure it runs the standard astro build with the adapter loaded
4. Update the astro-sst adapter to the latest version compatible with your SST version

Example fix

// before (astro.config.mjs)
export default defineConfig({ integrations: [] });
// after
import astroSst from "astro-sst";
export default defineConfig({ integrations: [astroSst()], output: "server" });

import fs from "fs";
import path from "path";
const metaPath = path.join(siteOutputPath, "dist", "sst.buildMeta.json");
if (!fs.existsSync(metaPath))
  throw new Error("sst.buildMeta.json missing — install/configure the astro-sst adapter and rebuild before sst deploy");

function hasBuildMeta(outputPath) {
  return fs.existsSync(path.join(outputPath, "dist", "sst.buildMeta.json"));
}

try {
  plan = buildPlan(outputPath);
} catch (e) {
  if (String(e).includes("Build metadata file not found")) {
    execSync("npm run build"); // rebuild with adapter
    plan = buildPlan(outputPath);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Incompatible "astro-sst" adapter version detected. The Astro
• Build ID not found in ".next/BUILD_ID" for site "${name}". E
• default Python Dockerfile not found at %s: %w
• Could not load OpenNext output file at "${openNextOutputPath
• Base path configuration not found in ".next/routes-manifest.

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/33c1481d4cad033d. Report an issue: GitHub.