apache/beam · error · UnsupportedOperationException

Unsupported distribution mode

Error message

Unsupported distribution mode: {distributionMode}

What it means

IcebergIO.WriteRows's expand dispatches on the configured distribution mode (NONE/HASH/ORDER, depending on version). When the mode does not match any implemented case, the default branch throws UnsupportedOperationException. This guards against a distribution mode value that is recognized by configuration but not implemented in the expansion logic.

Solutions

Set the write's distribution mode to a supported value (e.g. NONE or HASH) matching your Beam version.
Upgrade Beam to a version whose expand() implements the mode you need.
Remove the explicit distribution mode so the default/none path is used.
Check IcebergIO source for the switch cases to confirm supported modes.

Example fix

// before
write.withDistributionMode(DistributionMode.ORDER);

// after
write.withDistributionMode(DistributionMode.HASH); // or NONE

Defensive patterns

Strategy: validation

Validate before calling

if (write.getDistributionMode() != DistributionMode.NONE
    && write.getDistributionMode() != DistributionMode.HASH) {
  throw new IllegalArgumentException("unsupported distribution mode");
}

Try / catch

try {
  write.expand(rows);
} catch (UnsupportedOperationException e) {
  LOG.error("Unsupported distribution mode: {}", e.getMessage());
}

Prevention

Use only NONE or HASH distribution modes unless your Beam version documents more.
Re-check supported modes after Beam upgrades.
Let the writer use its default distribution mode.
Test write pipelines on the target runner version.

When it happens

Trigger: Building an IcebergIO write with a distribution mode not handled by the switch at IcebergIO.java:581, e.g. a mode set programmatically to a non-standard or newly added enum value.

Common situations: Upgrading Beam and enabling a newer distribution mode not supported by the deployed runner/version; setting distribution mode via generic config that admits values beyond the implemented ones; typos handled elsewhere but mode enum extended without updating expand().

Related errors

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

Appendix: source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergIO.java:581

                      destinations,
                      getTriggeringFrequency(),
                      getDirectWriteByteLimit(),
                      getWriteProperties()));
        case HASH:
          return input
              .apply(
                  "AssignDestinationAndPartition",
                  new AssignDestinationsAndPartitions(destinations, getCatalogConfig()))
              .apply(
                  "Write Rows to Partitions",
                  new WriteToPartitions(
                      getCatalogConfig(),
                      destinations,
                      getTriggeringFrequency(),
                      getAutoSharding(),
                      getWriteProperties()));
        default:
          throw new UnsupportedOperationException(
              "Unsupported distribution mode: " + getDistributionMode());
      }
    }
  }

  public static ReadRows readRows(IcebergCatalogConfig catalogConfig) {
    return new AutoValue_IcebergIO_ReadRows.Builder()
        .setCatalogConfig(catalogConfig)
        .setUseCdc(false)
        .setMetadataColumns(ImmutableList.of())
        .build();
  }

  @AutoValue
  public abstract static class ReadRows extends PTransform<PBegin, PCollection<Row>> {
    public enum StartingStrategy {
      EARLIEST,
      LATEST

View on GitHub (pinned to 12126d8942)