{"record":{"id":"c5155e4fab996fe8","repo":"apache/beam","slug":"unable-to-subscribe-to-read-queueurl","errorCode":null,"errorMessage":"Unable to subscribe to read.queueUrl(): ","messagePattern":"Unable to subscribe to read\\.queueUrl\\(\\): ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/sqs/SqsUnboundedSource.java","lineNumber":56,"sourceCode":"    this.read = read;\n  }\n\n  @Override\n  public List<SqsUnboundedSource> split(int desiredNumSplits, PipelineOptions options) {\n    List<SqsUnboundedSource> sources = new ArrayList<>();\n    for (int i = 0; i < Math.max(1, desiredNumSplits); ++i) {\n      sources.add(new SqsUnboundedSource(read));\n    }\n    return sources;\n  }\n\n  @Override\n  public UnboundedReader<SqsMessage> createReader(\n      PipelineOptions options, @Nullable SqsCheckpointMark checkpointMark) {\n    try {\n      return new SqsUnboundedReader(this, checkpointMark, options.as(AwsOptions.class));\n    } catch (IOException e) {\n      throw new RuntimeException(\"Unable to subscribe to \" + read.queueUrl() + \": \", e);\n    }\n  }\n\n  @Override\n  public Coder<SqsCheckpointMark> getCheckpointMarkCoder() {\n    return SerializableCoder.of(SqsCheckpointMark.class);\n  }\n\n  @Override\n  public Coder<SqsMessage> getOutputCoder() {\n    return SerializableCoder.of(SqsMessage.class);\n  }\n\n  public Read getRead() {\n    return read;\n  }\n\n  @Override","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/sqs/SqsUnboundedSource.java#L38-L74","documentation":"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.","triggerScenarios":"new SqsUnboundedReader(...) throws IOException during createReader — typically queue URL validation failure or an AWS client error at reader initialization.","commonSituations":"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.","solutions":["Check the queueUrl in the pipeline options — verify it exists with aws sqs get-queue-attributes.","Ensure AwsOptions has correct region and credentials are resolvable in the execution environment.","Fix the underlying IOException cause shown in the chained exception's cause field.","Verify network connectivity from the runner workers to the SQS endpoint (VPC endpoints/proxy)."],"exampleFix":"// before\n.apply(SqsIO.read().withQueueUrl(\"https://sqs.us-east-1.amazonaws.com/123/typoQueue\"));\n// after\n.apply(SqsIO.read().withQueueUrl(\"https://sqs.us-east-1.amazonaws.com/123456789012/my-queue\"));\n// and set region/credentials via --awsRegion=us-east-1","handlingStrategy":"validation","validationCode":"aws sqs get-queue-attributes --queue-url $QUEUE_URL --region $REGION  # must succeed with the same credentials the pipeline uses","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.run().waitUntilFinish();\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Unable to subscribe to\")) {\n    log.error(\"SQS subscribe failed; check queueUrl/credentials/region\", e.getCause());\n  }\n}","preventionTips":["Validate queueUrl with AWS CLI before launching the pipeline","Set --awsRegion explicitly in pipeline options","Use Workload Identity / instance profiles instead of static keys","Add integration smoke test reading one message before production runs"],"tags":["aws","sqs","subscribe","runtime-exception"],"backgroundTag":"resource-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}