anomalyco/sst · error · VisibleError

Cannot subscribe to the "${this.constructorName}" queue mult

Error message

Cannot subscribe to the "${this.constructorName}" queue multiple times. An SQS Queue can only have one subscriber.

What it means

SQS allows only one event source mapping per queue, so a Queue component permits a single subscribe() call. A second call while this.isSubscribed is true throws this VisibleError.

Source

Thrown at platform/src/components/aws/queue.ts:515

   * queue.subscribe({
   *   handler: "src/subscriber.handler",
   *   timeout: "60 seconds"
   * });
   * ```
   *
   * Or pass in the ARN of an existing Lambda function.
   *
   * ```js title="sst.config.ts"
   * queue.subscribe("arn:aws:lambda:us-east-1:123456789012:function:my-function");
   * ```
   */
  public subscribe(
    subscriber: Input<string | FunctionArgs | FunctionArn>,
    args?: QueueSubscriberArgs,
    opts?: ComponentResourceOptions,
  ) {
    if (this.isSubscribed)
      throw new VisibleError(
        `Cannot subscribe to the "${this.constructorName}" queue multiple times. An SQS Queue can only have one subscriber.`,
      );
    this.isSubscribed = true;

    return Queue._subscribeFunction(
      this.constructorName,
      this.arn,
      subscriber,
      args,
      { ...opts, provider: this.constructorOpts.provider },
    );
  }

  /**
   * Subscribe to an SQS Queue that was not created in your app.
   *
   * @param queueArn The ARN of the SQS Queue to subscribe to.
   * @param subscriber The function that'll be notified.

View on GitHub (pinned to a0bd20f762)

Solutions

Remove the duplicate subscribe() call
Use SNS, EventBridge, or a fan-out pattern if multiple consumers are needed
Subscribe once with a single handler that dispatches internally

Example fix

// before
queue.subscribe("src/consumerA.handler");
queue.subscribe("src/consumerB.handler");
// after
queue.subscribe("src/consumer.handler"); // single handler routes work internally
// or: fan out via SNS/EventBus to multiple subscribers

Defensive patterns

Strategy: validation

Validate before calling

if (queue.__isSubscribed) throw new Error("Queue already has a subscriber");
// track subscriptions in your own app-level map before calling subscribe

Type guard

const subscribed = new Set<string>();
function canSubscribe(queueName: string): boolean {
  return !subscribed.has(queueName);
}

Try / catch

try {
  queue.subscribe(handler);
} catch (e) {
  if (String(e).includes("only have one subscriber")) console.error("Use SNS/EventBridge fan-out for multiple consumers");
  throw e;
}

Prevention

Call subscribe() exactly once per Queue
Use SNS or EventBridge when multiple consumers are needed
Search codebase for queue name usages before adding a second subscriber

When it happens

Trigger: Calling queue.subscribe() twice on the same Queue component instance, e.g. wiring two consumers to one queue.

Common situations: Refactoring where a queue is shared by multiple handlers; forgetting SST's one-subscriber constraint versus SNS/EventBridge fan-out.

Related errors

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