{"record":{"id":"64276fd1125af710","repo":"apache/beam","slug":"sqltransform-currently-only-supports-a-single-dead-letter","errorCode":null,"errorMessage":"SqlTransform currently only supports a single dead letter queue collection","messagePattern":"SqlTransform currently only supports a single dead letter queue collection","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/SqlTransformSchemaTransformProvider.java","lineNumber":239,"sourceCode":"\n      // TODO: See about reimplementing a correct version of SqlTransform\n      ErrorCapture errors = new ErrorCapture();\n      PCollection<Row> output = input.apply(transform.withErrorsTransformer(errors));\n\n      // TODO: One possibility for capturing the required tables would be to inject a\n      // tableprovider\n      // that we control and see which tables are requested during expansion. We could then\n      // modify the output schema to reflect these inputs via options for better validation.\n\n      List<PCollection<Row>> errorList = errors.getInputs();\n      if (errorList.size() == 0) {\n        PCollection<Row> emptyErrors =\n            input.getPipeline().apply(Create.empty(BeamSqlRelUtils.getErrorRowSchema(Schema.of())));\n        return PCollectionRowTuple.of(\"output\", output, \"errors\", emptyErrors);\n      } else if (errorList.size() == 1) {\n        return PCollectionRowTuple.of(\"output\", output, \"errors\", errorList.get(0));\n      } else {\n        throw new UnsupportedOperationException(\n            \"SqlTransform currently only supports a single dead letter queue collection\");\n      }\n    }\n  }\n}\n","sourceCodeStart":221,"sourceCodeEnd":245,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/SqlTransformSchemaTransformProvider.java#L221-L245","documentation":"SqlTransform's SchemaTransform expansion routes dead letter queue (error) collections to an 'errors' output. The provider only supports wiring exactly one such collection; when more than one error PCollection is produced, expand throws UnsupportedOperationException.","triggerScenarios":"Calling expand/output when the expanded SqlTransform's error handling produces two or more error PCollections (errorList.size() > 1).","commonSituations":"Combining SQL transforms with multiple failure-tagging outputs; custom error handling extensions emitting several DLQs; evolving Beam SQL versions that changed error output cardinality.","solutions":["Restructure the pipeline so the SQL transform emits at most one dead letter collection.","Split the SQL transform into multiple steps, each producing a single error output.","Check the Beam version; newer releases may support multiple DLQs — upgrade if available."],"exampleFix":"// before\n// single transform producing multiple error outputs\n// after\n// apply transforms individually so each yields one DLQ:\nPCollectionRowTuple r =\n    PCollectionRowTuple.of(\"input\", rows)\n        .apply(SqlTransformSchemaTransformProvider..., configWithQuery1);\nPCollectionRowTuple r2 =\n    PCollectionRowTuple.of(\"input\", rows2)\n        .apply(..., configWithQuery2);","handlingStrategy":"try-catch","validationCode":"if (errorOutputs != null && errorOutputs.size() > 1) {\n  throw new IllegalArgumentException(\"Merge or split error collections before SqlTransform expansion\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  tuple = tuple.apply(sqlTransformProvider.buildTransform(config));\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"single dead letter queue\")) {\n    // restructure pipeline to emit one DLQ\n  }\n}","preventionTips":["Keep error handling to a single DLQ per SQL transform step.","Split complex SQL into sequential transforms when multiple failure outputs arise.","Check Beam release notes for multi-DLQ support before designing multiple error outputs."],"tags":["java","beam-sql","unsupported-feature"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}