anomalyco/sst · error · VisibleError

There have been some minor changes to the "Cluster" componen

Error message

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

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

What it means

SST tags referenced Cluster components with a component version (sst:ref:version). When a stage references a cluster created in another stage, the minor versions must match because cross-stage references rely on identical component output shape. A minor version mismatch means the referenced cluster was deployed with an older SST version and must be redeployed.

Source

Thrown at platform/src/components/aws/cluster.ts:249

    const vpc = normalizeVpc();
    const cluster = createCluster();
    createCapacityProviders();

    this.cluster = output(cluster);
    this._vpc = vpc;

    function reference() {
      const ref = args as ClusterRef;
      const cluster = ecs.Cluster.get(`${name}Cluster`, ref.id, undefined, {
        parent: self,
      });
      const clusterValidated = cluster.tagsAll.apply((tags) => {
        const refVersion = tags?.["sst:ref:version"]
          ? parseComponentVersion(tags["sst:ref:version"])
          : undefined;

        if (refVersion?.minor !== _version.minor) {
          throw new VisibleError(
            [
              `There have been some minor changes to the "Cluster" component that's being referenced by "${name}".\n`,
              `To update, you'll need to redeploy the stage where the cluster was created. And then redeploy this stage.`,
            ].join("\n"),
          );
        }

        registerVersion(refVersion);

        return cluster;
      });

      return { cluster: clusterValidated };
    }

    function normalizeVpc() {
      // "vpc" is a Vpc.v1 component
      if (args.vpc instanceof VpcV1) {

View on GitHub (pinned to a0bd20f762)

Solutions

Upgrade SST to the same version in the stage/project that created the Cluster and redeploy that stage (sst deploy).
Then redeploy the referencing stage so both sides use matching component versions.
Pin SST to an identical version across all apps/stages sharing resources (e.g. same package.json version).

Example fix

// repo A (cluster owner)
// package.json: "sst": "3.x.y" -> upgrade to same version as repo B, then:
// sst deploy --stage prod
// repo B
const cluster = sst.aws.Cluster.reference('MyCluster', { cluster: 'prod/my-app/MyCluster' }); // redeploy after repo A

Defensive patterns

Strategy: validation

Validate before calling

// Before referencing, check the owning stage's SST version matches:
const SST_VERSION = require('./package.json').dependencies.sst;
if (SST_VERSION !== OWNER_STAGE_SST_VERSION)
  console.warn(`Redeploy the cluster owner stage: SST ${SST_VERSION} vs ${OWNER_STAGE_SST_VERSION}`);

Prevention

Pin the same SST version across all repos/stages sharing components.
Upgrade SST everywhere and redeploy owner stages first, then referencing stages.
Watch the sst:ref:version tag on the cluster when debugging.

When it happens

Trigger: Calling Cluster.reference(...) (or a component like Service that references a cluster) in stage B, pointing at a cluster deployed in stage A with a different SST minor version of the Cluster component.

Common situations: Upgrading SST in one app/stage but not the stage that owns the cluster; multiple repos sharing a cluster where only one repo bumped SST; stale dev stage referencing an old prod cluster.

Related errors

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