{"record":{"id":"5452b66e7212875e","repo":"anomalyco/sst","slug":"incompatible-astro-sst-adapter-version-detected","errorCode":null,"errorMessage":"Incompatible \"astro-sst\" adapter version detected. The Astro component requires \"astro-sst\" adapter version 3.1.2 or later.","messagePattern":"Incompatible \"astro-sst\" adapter version detected\\. The Astro component requires \"astro-sst\" adapter version 3\\.1\\.2 or later\\.","errorType":"exception","errorClass":"VisibleError","httpStatus":null,"severity":"error","filePath":"platform/src/components/aws/astro.ts","lineNumber":431,"sourceCode":"        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(\n          `Incompatible \"astro-sst\" adapter version detected. The Astro component requires \"astro-sst\" adapter version 3.1.2 or later.`,\n        );\n      }\n\n      // Note about handling 404 pages. Here is Astro's behavior:\n      // - when static/prerendered, Astro builds a /404.html file in the client build output dir\n      // - when SSR, Astro server handles /404 route\n      //\n      // 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.\n      //\n      // So here is what we do when a request comes in for ie. /garbage:\n      //\n      // - Case 1: static (no server) => In CF function S3 look up will fail, and uri will rewrite to /404.html\n      //   x that's why we set `plan.custom404` to `/404.html`\n      //\n      // - 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.\n      //   x that's why we configure `plan.server.copyFiles` include /404.html\n      //","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/anomalyco/sst/blob/a0bd20f762883e72a35caccb4896c42ce5b3f707/platform/src/components/aws/astro.ts#L413-L449","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade the adapter: `npm install astro-sst@latest` (>= 3.1.2), rebuild the site, and redeploy","Remove the old lockfile entry / delete node_modules and lockfile if the upgrade doesn't take, then reinstall","Pin astro-sst to a known-good >= 3.1.2 version in package.json"],"exampleFix":"// before (package.json)\n\"astro-sst\": \"^2.8.0\"\n// after\n\"astro-sst\": \"^3.1.2\" // then: npm install && npm run build","handlingStrategy":"validation","validationCode":"import fs from \"fs\";\nimport path from \"path\";\nconst meta = JSON.parse(fs.readFileSync(path.join(out, \"dist\", \"sst.buildMeta.json\"), \"utf-8\"));\nconst [maj, min, patch] = meta.pluginVersion?.split(\".\").map(Number) ?? [];\nif (!meta.pluginVersion || maj < 3 || (maj === 3 && (min < 1 || (min === 1 && patch < 2))))\n  throw new Error(\"astro-sst >= 3.1.2 required — upgrade the adapter and rebuild\");","typeGuard":"function isCompatibleAdapter(meta, min = \"3.1.2\") {\n  const cmp = (a, b) => a.map(Number).reduce((r, n, i) => r ?? (n - b[i] || 0), null) ?? 0;\n  const c = cmp(meta.pluginVersion?.split(\".\") ?? [0,0,0], min.split(\".\"));\n  return c >= 0;\n}","tryCatchPattern":"try {\n  plan = buildPlan(outputPath);\n} catch (e) {\n  if (String(e).includes(\"Incompatible\") || String(e).includes(\"3.1.2\")) {\n    throw new Error(\"Run: npm install astro-sst@latest && npm run build, then redeploy\");\n  }\n  throw e;\n}","preventionTips":["Pin astro-sst to ^3.1.2 (or latest) in package.json","Commit an updated lockfile whenever you bump SST so adapter and platform stay in sync","Check meta.pluginVersion in a predeploy script to fail fast","Keep adapter and SST platform versions upgraded together"],"tags":["astro","version-mismatch","adapter","dependency"],"backgroundTag":"dependency-version-incompatible","analyzedSha":"a0bd20f762883e72a35caccb4896c42ce5b3f707","analyzedAt":"2026-08-30T11:26:00.383Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}