anomalyco/sst · error · VisibleError

Incompatible "astro-sst" adapter version detected. The Astro

Error message

Incompatible "astro-sst" adapter version detected. The Astro component requires "astro-sst" adapter version 3.1.2 or later.

What it means

SST reads `pluginVersion` from the `sst.buildMeta.json` emitted by the astro-sst adapter and requires >= 3.1.2. Older adapters don't emit the needed metadata (or emit incompatible route plans), so SST hard-fails rather than deploying a broken site.

Source

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

        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(
          `Incompatible "astro-sst" adapter version detected. The Astro component requires "astro-sst" adapter version 3.1.2 or later.`,
        );
      }

      // Note about handling 404 pages. Here is Astro's behavior:
      // - when static/prerendered, Astro builds a /404.html file in the client build output dir
      // - when SSR, Astro server handles /404 route
      //
      // We could handle the /404.html with CloudFront's custom error response feature, but that will not work when routing the Astro through the `Router` component. It does not make sense for `Router` to have a custom error response shared across all routes (ie. API). Each route's 404 behavior are different.
      //
      // So here is what we do when a request comes in for ie. /garbage:
      //
      // - Case 1: static (no server) => In CF function S3 look up will fail, and uri will rewrite to /404.html
      //   x that's why we set `plan.custom404` to `/404.html`
      //
      // - Case 2: prerendered (has server) => In CF function S3 look up will fail, and request will be sent to the server function. Server fails to serve /garbage, and cannot find the route. Server tries to serve /404, and cannot find the route. Server finally serves the 404.html file manually bundled into it.
      //   x that's why we configure `plan.server.copyFiles` include /404.html
      //

View on GitHub (pinned to a0bd20f762)

Solutions

1. Upgrade the adapter: `npm install astro-sst@latest` (>= 3.1.2), rebuild the site, and redeploy
2. Remove the old lockfile entry / delete node_modules and lockfile if the upgrade doesn't take, then reinstall
3. Pin astro-sst to a known-good >= 3.1.2 version in package.json

Example fix

// before (package.json)
"astro-sst": "^2.8.0"
// after
"astro-sst": "^3.1.2" // then: npm install && npm run build

import fs from "fs";
import path from "path";
const meta = JSON.parse(fs.readFileSync(path.join(out, "dist", "sst.buildMeta.json"), "utf-8"));
const [maj, min, patch] = meta.pluginVersion?.split(".").map(Number) ?? [];
if (!meta.pluginVersion || maj < 3 || (maj === 3 && (min < 1 || (min === 1 && patch < 2))))
  throw new Error("astro-sst >= 3.1.2 required — upgrade the adapter and rebuild");

function isCompatibleAdapter(meta, min = "3.1.2") {
  const cmp = (a, b) => a.map(Number).reduce((r, n, i) => r ?? (n - b[i] || 0), null) ?? 0;
  const c = cmp(meta.pluginVersion?.split(".") ?? [0,0,0], min.split("."));
  return c >= 0;
}

try {
  plan = buildPlan(outputPath);
} catch (e) {
  if (String(e).includes("Incompatible") || String(e).includes("3.1.2")) {
    throw new Error("Run: npm install astro-sst@latest && npm run build, then redeploy");
  }
  throw e;
}

When it happens

Trigger: Deploying `sst.aws.Astro` against a site built with astro-sst < 3.1.2, or a build where `pluginVersion` is missing from sst.buildMeta.json (very old adapter).

Common situations: Package manager lockfile pinning an old astro-sst version; upgrading SST (platform) without upgrading the adapter; a fresh clone where the lockfile predates the adapter bump.

Related errors

• Build metadata file not found at "${filePath}". Update your
• There have been some minor changes to the "Cluster" componen
• SSR server bundle not found in the build output at: "${pat

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