apache/beam · error · IllegalArgumentException

Beam write property '%s' is not supported. Writing to Delta

Error message

Beam write property '%s' is not supported. Writing to Delta Lake tables is currently not supported.

What it means

DeltaTable.validateTableProperties rejects any table property whose key starts with the Beam write property prefix, because there is no Delta Lake sink in Beam yet. The error tells you that a write-related Beam property was supplied to a Delta table, which cannot honor it.

Source

Thrown at sdks/java/extensions/sql/delta/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/delta/DeltaTable.java:83

  DeltaTable(String tableLocation, Table table) {
    super(table.getSchema());
    this.schema = table.getSchema();
    this.tableLocation = tableLocation;

    Long parsedVersion = null;
    String parsedTimestamp = null;
    Map<String, String> parsedHadoopConfig = new HashMap<>();

    ObjectNode properties = table.getProperties();
    for (Map.Entry<String, JsonNode> property : properties.properties()) {
      String key = property.getKey();
      String lowerKey = key.toLowerCase();
      JsonNode val = property.getValue();

      if (lowerKey.startsWith(BEAM_WRITE_PROPERTY)) {
        // TODO: Support writing to Delta Lake tables once a Delta Lake sink is
        // available.
        throw new IllegalArgumentException(
            String.format(
                "Beam write property '%s' is not supported. Writing to Delta Lake tables is currently not supported.",
                key));
      } else if (lowerKey.startsWith(BEAM_READ_PROPERTY)) {
        // none supported yet
        throw new IllegalArgumentException("Unknown Beam read property: " + key);
      } else if (lowerKey.equalsIgnoreCase(VERSION_FIELD)) {
        parsedVersion = parseVersion(val);
      } else if (lowerKey.equalsIgnoreCase(TIMESTAMP_FIELD)) {
        parsedTimestamp = val.asText();
      } else if (lowerKey.equalsIgnoreCase(HADOOP_CONFIG_FIELD)
          || lowerKey.equalsIgnoreCase(HADOOP_CONFIG_CAMEL_FIELD)) {
        parseHadoopConfig(val, parsedHadoopConfig);
      } else {
        throw new IllegalArgumentException(String.format("Unknown property '%s'", key));
      }
    }

View on GitHub (pinned to 12126d8942)

Solutions

Remove the 'beam_write_*' property from the Delta table's properties.
If you need to write to the table, use a different provider that supports sinks, or write via Delta Lake tooling outside Beam.
Check the Beam version's Delta provider docs for the supported property list.

Example fix

// before
CREATE EXTERNAL TABLE delta_t ... TBLPROPERTIES { 'beam_write_partition_columns': 'date' }
// after
CREATE EXTERNAL TABLE delta_t ... -- no beam_write properties

Defensive patterns

Strategy: validation

Validate before calling

// before building the Delta table
properties.keySet().forEach(k -> {
  if (k.toLowerCase().startsWith("beam_write")) {
    throw new IllegalArgumentException("beam_write property " + k + " not supported for Delta Lake");
  }
});

Try / catch

try {
  table = new DeltaTable(tableId, schema, properties);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("not supported")) {
    properties = properties.entrySet().stream()
        .filter(en -> !en.getKey().toLowerCase().startsWith("beam_write"))
        .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
  }
}

Prevention

Do not copy TBLPROPERTIES from writable providers onto Delta tables.
Check the provider docs for the supported property whitelist.
Centralize table property definitions so provider-specific keys don't leak across providers.

When it happens

Trigger: Creating or validating a DeltaTable whose properties map contains a key starting with 'beam_write' (BEAM_WRITE_PROPERTY), e.g. in CREATE EXTERNAL TABLE ... TBLPROPERTIES or table configuration.

Common situations: Copy-pasting table properties from other providers (Iceberg, text, BigQuery) that support Beam write properties; misconfiguring a DDL statement intended for a writable sink but targeting Delta Lake.

Related errors

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