apache/beam · error · RuntimeException

Unable to subscribe to read.queueUrl():

Error message

Unable to subscribe to read.queueUrl(): 

What it means

SqsUnboundedSource.createReader wraps any IOException thrown while constructing SqsUnboundedReader (queue subscription) in a RuntimeException prefixed with 'Unable to subscribe to <queueUrl>:'. It signals that the source could not start consuming from the SQS queue.

Source

Thrown at sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/sqs/SqsUnboundedSource.java:56

    this.read = read;
  }

  @Override
  public List<SqsUnboundedSource> split(int desiredNumSplits, PipelineOptions options) {
    List<SqsUnboundedSource> sources = new ArrayList<>();
    for (int i = 0; i < Math.max(1, desiredNumSplits); ++i) {
      sources.add(new SqsUnboundedSource(read));
    }
    return sources;
  }

  @Override
  public UnboundedReader<SqsMessage> createReader(
      PipelineOptions options, @Nullable SqsCheckpointMark checkpointMark) {
    try {
      return new SqsUnboundedReader(this, checkpointMark, options.as(AwsOptions.class));
    } catch (IOException e) {
      throw new RuntimeException("Unable to subscribe to " + read.queueUrl() + ": ", e);
    }
  }

  @Override
  public Coder<SqsCheckpointMark> getCheckpointMarkCoder() {
    return SerializableCoder.of(SqsCheckpointMark.class);
  }

  @Override
  public Coder<SqsMessage> getOutputCoder() {
    return SerializableCoder.of(SqsMessage.class);
  }

  public Read getRead() {
    return read;
  }

  @Override

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the queueUrl in the pipeline options — verify it exists with aws sqs get-queue-attributes.
2. Ensure AwsOptions has correct region and credentials are resolvable in the execution environment.
3. Fix the underlying IOException cause shown in the chained exception's cause field.
4. Verify network connectivity from the runner workers to the SQS endpoint (VPC endpoints/proxy).

Example fix

// before
.apply(SqsIO.read().withQueueUrl("https://sqs.us-east-1.amazonaws.com/123/typoQueue"));
// after
.apply(SqsIO.read().withQueueUrl("https://sqs.us-east-1.amazonaws.com/123456789012/my-queue"));
// and set region/credentials via --awsRegion=us-east-1

aws sqs get-queue-attributes --queue-url $QUEUE_URL --region $REGION  # must succeed with the same credentials the pipeline uses

try {
  pipeline.run().waitUntilFinish();
} catch (RuntimeException e) {
  if (e.getMessage().startsWith("Unable to subscribe to")) {
    log.error("SQS subscribe failed; check queueUrl/credentials/region", e.getCause());
  }
}

When it happens

Trigger: new SqsUnboundedReader(...) throws IOException during createReader — typically queue URL validation failure or an AWS client error at reader initialization.

Common situations: Wrong/typo'd queue URL in SqsIO.read().withQueueUrl(), missing AWS region/credentials in AwsOptions, queue deleted or in another account, network/VPC egress blocked.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed to delete pendingDeletes.size() messages after retrie
• Failed to extend visibility timeout for messages.size() mess
• Failed to determine if the source is splittable
• Failed to get metadata from MatchResult: %s.
• Failure to register coder

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/c5155e4fab996fe8. Report an issue: GitHub.