anomalyco/sst · error · VisibleError

Missing "vpc.containerSubnets" for the "${name}" Cluster com

Error message

Missing "vpc.containerSubnets" for the "${name}" Cluster component.

What it means

After deprecating serviceSubnets, Cluster requires subnet IDs under vpc.containerSubnets so it knows which subnets to place tasks/containers in. If neither containerSubnets nor serviceSubnets is provided, SST cannot place the cluster's services and throws.

Source

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

      if (args.vpc instanceof VpcV1) {
        throw new VisibleError(
          `You are using the "Vpc.v1" component. Please migrate to the latest "Vpc" component.`,
        );
      }

      // "vpc" is a Vpc component
      if (args.vpc instanceof Vpc) {
        return args.vpc;
      }

      // "vpc" is object
      return output(args.vpc).apply((vpc) => {
        if (vpc.containerSubnets && vpc.serviceSubnets)
          throw new VisibleError(
            `You cannot provide both "vpc.containerSubnets" and "vpc.serviceSubnets" in the "${name}" Cluster component. The "serviceSubnets" property has been deprecated. Use "containerSubnets" instead.`,
          );
        if (!vpc.containerSubnets && !vpc.serviceSubnets)
          throw new VisibleError(
            `Missing "vpc.containerSubnets" for the "${name}" Cluster component.`,
          );

        if (
          (vpc.cloudmapNamespaceId && !vpc.cloudmapNamespaceName) ||
          (!vpc.cloudmapNamespaceId && vpc.cloudmapNamespaceName)
        )
          throw new VisibleError(
            `You must provide both "vpc.cloudmapNamespaceId" and "vpc.cloudmapNamespaceName" for the "${name}" Cluster component.`,
          );

        return {
          ...vpc,
          containerSubnets: (vpc.containerSubnets ?? vpc.serviceSubnets)!,
          serviceSubnets: undefined,
        };
      });
    }

View on GitHub (pinned to a0bd20f762)

Solutions

Provide vpc.containerSubnets with an array of private subnet IDs from your VPC.
Alternatively pass a sst.aws.Vpc component instance instead of a raw object.
Ensure the given subnets are routable by your tasks (typically private subnets with NAT).

Example fix

// before
const cluster = new sst.aws.Cluster('MyCluster', { vpc: {} });
// after
const cluster = new sst.aws.Cluster('MyCluster', {
  vpc: { containerSubnets: ['subnet-0abc', 'subnet-1def'] }
});

Defensive patterns

Strategy: validation

Validate before calling

function requireContainerSubnets(vpc) {
  if (!vpc?.containerSubnets && !vpc?.serviceSubnets)
    throw new Error('Cluster vpc.containerSubnets is required (array of subnet IDs)');
}
requireContainerSubnets(vpcConfig);

Type guard

const hasContainerSubnets = (vpc) => Array.isArray(vpc?.containerSubnets) && vpc.containerSubnets.length > 0;

Prevention

Always wire containerSubnets from a sst.aws.Vpc instance's outputs instead of hand-writing an empty object.
Check subnet IDs exist in the target region before deploy.
Use private subnets with NAT for ECS tasks.

When it happens

Trigger: new sst.aws.Cluster('X', { vpc: {} }) or vpc: { cloudmapNamespaceId: ... } with no subnets — normalizeVpc's !containerSubnets && !serviceSubnets branch fires.

Common situations: VPC arg left as an empty object after removing deprecated fields; switching from a Vpc component instance to a raw object but forgetting subnets; partially deleted config.

Related errors

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