apache/beam · error · IllegalArgumentException

Unknown Beam read property: {key}

Error message

Unknown Beam read property: {key}

What it means

DeltaTable.validateTableProperties rejects any property starting with the Beam read property prefix because the Delta provider currently supports no read properties at all. Any 'beam_read_*' key supplied is treated as unknown and rejected with IllegalArgumentException.

Source

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

    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));
      }
    }

    if (parsedVersion != null && parsedTimestamp != null) {
      throw new IllegalArgumentException("Cannot set both version and timestamp.");
    }

    this.version = parsedVersion;
    this.timestamp = parsedTimestamp;

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove the 'beam_read_*' property from the Delta table configuration.
2. Configure reading behavior through the supported keys instead: 'version', 'timestamp', or 'hadoop_config'.
3. Upgrade Beam and check if the Delta provider has gained read-property support.

Example fix

// before
TBLPROPERTIES { 'beam_read_format': 'delta' }
// after
TBLPROPERTIES { 'version': '5' }

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

try {
  table = new DeltaTable(tableId, schema, properties);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown Beam read property")) {
    // strip beam_read_* keys and retry with only version/timestamp/hadoop_config
  }
}

When it happens

Trigger: Passing a 'beam_read_*' key in the Delta table's properties during table creation or validation.

Common situations: Reusing property definitions from providers like text/parquet that support beam_read properties (e.g. format, compression) against a Delta table.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Beam write property '%s' is not supported. Writing to Delta
• Unknown property '%s'
• Cannot set both version and timestamp.
• Failed to parse hadoop_config string as JSON
• %s does not support predicate/project push-down, yet non-emp

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