anomalyco/sst · error · VisibleError

There have been some minor changes to the "Router" component

Error message

There have been some minor changes to the "Router" component that's being referenced by "${name}".

To update, you'll need to redeploy the stage where the Router was created. And then redeploy this stage.

What it means

When a stage references a Router created in another stage via a RouterRef, SST stamps the underlying CloudFront distribution with an `sst:ref:version` tag. If the referenced distribution's version tag does not match the current expected `_refVersion`, the component fails with instructions to redeploy both stages, because the referenced Router was created with an older/incompatible component version.

Source

Thrown at platform/src/components/aws/router.ts:1437

      const r = handleLazyRoutes();
      cdn = output(r.distribution);
      kvStoreArn = r.kvStoreArn;
      kvNamespace = output(r.kvNamespace);
    }

    this.cdn = cdn;
    this.kvStoreArn = kvStoreArn;
    this.kvNamespace = kvNamespace;
    this.hasInlineRoutes = output(hasInlineRoutes);
    this._protectionMode = protection;
    registerOutputs();

    function reference() {
      const ref = args as unknown as RouterRef;
      const cdn = Cdn.get(`${name}Cdn`, ref.distributionID, { parent: self });
      const tags = cdn.nodes.distribution.tagsAll.apply((tags) => {
        if (tags?.["sst:ref:version"] !== _refVersion.toString()) {
          throw new VisibleError(
            [
              `There have been some minor changes to the "Router" component that's being referenced by "${name}".\n`,
              `To update, you'll need to redeploy the stage where the Router was created. And then redeploy this stage.`,
            ].join("\n"),
          );
        }

        return {
          kvStoreArn: tags?.["sst:ref:kv"],
          kvNamespace: tags?.["sst:ref:kv-namespace"],
          hasInlineRoutes: tags?.["sst:ref:kv"] === undefined,
          protection: tags?.["sst:ref:protection"] ?? "none",
        };
      });

      return {
        cdn,
        kvStoreArn: tags.kvStoreArn,

View on GitHub (pinned to a0bd20f762)

Solutions

1. Redeploy the stage where the Router was originally created (so its distribution gets the new ref version tag), then redeploy the referencing stage
2. Upgrade SST to the same version across all stages and deploy the Router-owning stage first
3. As a last resort, recreate the referenced Router in its own stage so the new version tag is applied

Example fix

// before
npx sst deploy --stage other-stage   # referencing stage only
// after
npx sst deploy --stage router-stage  # owner first
npx sst deploy --stage other-stage   # then referrer

import { GetResource } from "@pulumi/pulumi";
// check the ref version tag before referencing:
// aws cmdline: aws cloudfront list-tags-for-resource --resource <distribution-arn>
// expect tag sst:ref:version to equal your current SST Router _refVersion

try {
  const router = Router.ref("MyRouter", { distributionID: id });
} catch (e) {
  if (String(e).includes("redeploy the stage where the Router was created")) {
    console.error("Redeploy owner stage first, then this stage");
  }
  throw e;
}

When it happens

Trigger: Calling `Router.ref(name, { distributionID, ... })` (via `reference`) where the fetched Cdn's `tagsAll["sst:ref:version"]` differs from `_refVersion` — the referenced stage was deployed with an older SST version of the Router component.

Common situations: Cross-stage references (e.g. prod stage referencing a Router built in another stage) after an SST upgrade; one stage redeployed but the stage owning the Router not yet updated.

Related errors

• Invalid route type
• Lambda@Edge requires a qualified ARN (with version). Got: ${
• Cannot set "protection" on a Router with inline routes. Use
• In "${name}" Router, the route path "${path}" must start wit
• In "${name}" Router, the route path "${path}" can only have

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