anomalyco/sst · error · VisibleError

You must provide a container name in "loadBalancer.rules" wh

Error message

You must provide a container name in "loadBalancer.rules" when there is more than one container.

What it means

When a Service runs more than one container, each load balancer rule must name which container it routes to. `normalizeLoadBalancer` validates every rule and throws this `VisibleError` if a rule lacks a `container` field in a multi-container service.

Source

Thrown at platform/src/components/aws/service.ts:1962

      const inlineLoadBalancer = output(loadBalancer).apply(
        (lb) => lb as Exclude<typeof lb, { instance: Alb }>,
      );

      // normalize rules
      const rules = all([inlineLoadBalancer, containers]).apply(
        ([lb, containers]) => {
          // validate rules
          const lbRules = lb.rules ?? lb.ports;
          if (!lbRules || lbRules.length === 0)
            throw new VisibleError(
              `You must provide the ports to expose via "loadBalancer.rules".`,
            );

          // validate container defined when multiple containers exists
          if (containers.length > 1) {
            lbRules.forEach((v) => {
              if (!v.container)
                throw new VisibleError(
                  `You must provide a container name in "loadBalancer.rules" when there is more than one container.`,
                );
            });
          }

          // parse protocols and ports
          const rules = lbRules.map((v) => {
            const listenParts = v.listen.split("/");
            const listenPort = parseInt(listenParts[0]);
            const listenProtocol = listenParts[1];
            const listenConditions =
              v.conditions || v.path
                ? {
                    path: v.conditions?.path ?? v.path,
                    query: v.conditions?.query,
                    header: v.conditions?.header,
                  }
                : undefined;

View on GitHub (pinned to a0bd20f762)

Solutions

Add `container: "api"` (the container's `name`) to each rule in `loadBalancer.rules`.
Ensure the referenced container name matches one of the `containers[].name` values exactly.
If rules target the same container, still specify it explicitly since SST cannot infer it with multiple containers.

Example fix

// before
loadBalancer: { rules: [{ listen: "443/https", forward: "80/http" }] }

// after
loadBalancer: { rules: [{ container: "api", listen: "443/https", forward: "80/http" }] }

Defensive patterns

Strategy: validation

Validate before calling

const containerNames = new Set(args.containers.map((c) => c.name));
if (args.containers.length > 1) {
  for (const r of args.loadBalancer.rules) {
    if (!r.container || !containerNames.has(r.container)) {
      throw new Error(`Rule must reference a defined container, got: ${r.container}`);
    }
  }
}

Type guard

function ruleHasContainer(r: { container?: string }, containers: { name: string }[]): r is { container: string } {
  return typeof r.container === "string" && containers.some((c) => c.name === r.container);
}

Try / catch

try {
  const svc = new sst.aws.Service("Api", args);
} catch (e) {
  if (e instanceof VisibleError && e.message.includes("container name")) {
    args.loadBalancer.rules.forEach((r) => (r.container ??= args.containers[0].name));
  } else throw e;
}

Prevention

Always set `container` in LB rules, even for single-container services.
Keep rule `container` values in sync with `containers[].name`.
Re-audit LB rules whenever adding or removing containers.

When it happens

Trigger: Defining two or more `containers` and a `loadBalancer.rules`/`ports` entry without `container: "<name>"`, on `sst deploy`.

Common situations: Adding a second (sidecar) container to an existing service whose rules were written when only one container existed; copying single-container examples into multi-container services.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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