anomalyco/sst · error · VisibleError

There have been some minor changes to the "Vpc" component th

Error message

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

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

What it means

When a stage references a VPC created in another stage via `sst.aws.Vpc.get`/`ref`, SST stamps the referenced VPC with an `sst:ref-version` tag derived from the component version. If the tag on the actual VPC does not match what this SST version expects, the reference path throws this VisibleError telling you the provider-side VPC was created by an older (or newer) component version and must be redeployed.

Source

Thrown at platform/src/components/aws/vpc.ts:482

    this.cloudmapNamespace = cloudmapNamespace;
    this.privateKeyValue = output(privateKeyValue);
    registerOutputs();

    function reference() {
      const ref = args as VpcRef;
      const vpc = ec2.Vpc.get(`${name}Vpc`, ref.vpcId, undefined, {
        parent: self,
      });

      const vpcId = vpc.tagsAll.apply((tags) => {
        registerVersion(
          tags?.["sst:component-version"]
            ? parseInt(tags["sst:component-version"])
            : undefined,
        );

        if (tags?.["sst:ref-version"] !== _refVersion.toString()) {
          throw new VisibleError(
            [
              `There have been some minor changes to the "Vpc" component that's being referenced by "${name}".\n`,
              `To update, you'll need to redeploy the stage where the VPC was created. And then redeploy this stage.`,
            ].join("\n"),
          );
        }

        return output(ref.vpcId);
      });

      const internetGateway = ec2.InternetGateway.get(
        `${name}InstanceGateway`,
        ec2.getInternetGatewayOutput(
          {
            filters: [{ name: "attachment.vpc-id", values: [vpcId] }],
          },
          { parent: self },
        ).internetGatewayId,

View on GitHub (pinned to a0bd20f762)

Solutions

In the stage where the VPC was created, run `sst upgrade` (to the same SST version) and `sst deploy` so the VPC is re-stamped with the new ref-version tag.
Then redeploy the current stage so its expected `_refVersion` matches the tag.
If the VPC stage cannot be redeployed, pin the current stage to the SST version that created the VPC.

Example fix

// before (versions out of sync)
# stage: infra  -> sst deploy (sst v0.x, old ref-version)
# stage: app    -> sst deploy (sst v0.y, expects new ref-version) // throws
// after
# stage: infra  -> sst upgrade && sst deploy   // re-tags VPC
# stage: app    -> sst deploy                 // versions match

Defensive patterns

Strategy: validation

Validate before calling

import { EC2Client, DescribeTagsCommand } from "@aws-sdk/client-ec2";
const tags = await new EC2Client({}).send(new DescribeTagsCommand({
  Filters: [{ Name: "resource-id", Values: [vpcId] }]
}));
const refVersion = tags.Tags?.find(t => t.Key === "sst:ref-version")?.Value;
if (!refVersion) throw new Error("VPC lacks sst:ref-version; redeploy the owning stage with the current SST version.");

Type guard

function hasMatchingRefVersion(tags: Record<string, string> | undefined, expected: string): boolean {
  return tags?.["sst:ref-version"] === expected;
}

Try / catch

try {
  const vpc = sst.aws.Vpc.get("Vpc", { id: vpcId });
} catch (e) {
  if (String(e).includes("minor changes to the \"Vpc\" component")) {
    console.error("Redeploy the stage that owns the VPC with the current SST version, then retry.");
  }
  throw e;
}

Prevention

Keep the same SST version across all stages, especially the stage that owns shared VPCs.
After an SST upgrade, redeploy the VPC-owning stage before any consuming stage.
Pin SST versions in CI so stages cannot drift silently.

When it happens

Trigger: Upgrading SST in the consumer stage (so `_refVersion` changes) while the stage that owns the VPC still has a VPC tagged with the old `sst:ref-version`; running `sst deploy` on a stage that does `Vpc.get` before redeploying the VPC-owning stage.

Common situations: Team upgrades SST in the app stage only; CI deploys the app stage against a stale dev-stage VPC; the VPC stage was deployed with a different SST version.

Related errors

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