apache/beam · error · UnsupportedOperationException

SqlTransform currently only supports a single dead letter…

Error message

SqlTransform currently only supports a single dead letter queue collection

What it means

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.

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.

Example fix

// before
// single transform producing multiple error outputs
// after
// apply transforms individually so each yields one DLQ:
PCollectionRowTuple r =
    PCollectionRowTuple.of("input", rows)
        .apply(SqlTransformSchemaTransformProvider..., configWithQuery1);
PCollectionRowTuple r2 =
    PCollectionRowTuple.of("input", rows2)
        .apply(..., configWithQuery2);

Defensive patterns

Strategy: try-catch

Validate before calling

if (errorOutputs != null && errorOutputs.size() > 1) {
  throw new IllegalArgumentException("Merge or split error collections before SqlTransform expansion");
}

Try / catch

try {
  tuple = tuple.apply(sqlTransformProvider.buildTransform(config));
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("single dead letter queue")) {
    // restructure pipeline to emit one DLQ
  }
}

Prevention

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.

When it happens

Trigger: Calling expand/output when the expanded SqlTransform's error handling produces two or more error PCollections (errorList.size() > 1).

Common situations: Combining SQL transforms with multiple failure-tagging outputs; custom error handling extensions emitting several DLQs; evolving Beam SQL versions that changed error output cardinality.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/SqlTransformSchemaTransformProvider.java:239

      // TODO: See about reimplementing a correct version of SqlTransform
      ErrorCapture errors = new ErrorCapture();
      PCollection<Row> output = input.apply(transform.withErrorsTransformer(errors));

      // TODO: One possibility for capturing the required tables would be to inject a
      // tableprovider
      // that we control and see which tables are requested during expansion. We could then
      // modify the output schema to reflect these inputs via options for better validation.

      List<PCollection<Row>> errorList = errors.getInputs();
      if (errorList.size() == 0) {
        PCollection<Row> emptyErrors =
            input.getPipeline().apply(Create.empty(BeamSqlRelUtils.getErrorRowSchema(Schema.of())));
        return PCollectionRowTuple.of("output", output, "errors", emptyErrors);
      } else if (errorList.size() == 1) {
        return PCollectionRowTuple.of("output", output, "errors", errorList.get(0));
      } else {
        throw new UnsupportedOperationException(
            "SqlTransform currently only supports a single dead letter queue collection");
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)