apache/beam · error · IllegalArgumentException

Unknown property '%s'

Error message

Unknown property '%s'

What it means

DeltaTable.validateTableProperties falls through to the else branch and throws IllegalArgumentException when a property key matches none of the recognized keys: beam_write prefix (rejected earlier), beam_read prefix, 'version', 'timestamp', and 'hadoop_config'/'hadoopConfig'. It prevents silently ignoring misspelled or unsupported options.

Source

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

      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;
    this.hadoopConfig = parsedHadoopConfig.isEmpty() ? null : parsedHadoopConfig;
  }

  private static Long parseVersion(JsonNode val) {
    if (val.isNumber()) {
      return val.asLong();
    }
    return Long.parseLong(val.asText());
  }

View on GitHub (pinned to 12126d8942)

Solutions

1. Use only the supported property keys: 'version', 'timestamp', 'hadoop_config' (or 'hadoopConfig').
2. Fix the spelling/casing of the property key in your DDL or configuration.
3. Remove properties copied from other providers that the Delta provider does not understand.

Example fix

// before
TBLPROPERTIES { 'hadoopConf': '...' }
// after
TBLPROPERTIES { 'hadoop_config': '{"fs.defaultFS":"hdfs://..."}' }

Set<String> ALLOWED = Set.of("version", "timestamp", "hadoop_config", "hadoopconfig");
properties.keySet().forEach(k -> {
  if (!ALLOWED.contains(k.toLowerCase()) && !k.toLowerCase().startsWith("beam_")) {
    throw new IllegalArgumentException("Unknown Delta property: " + k);
  }
});

try {
  table = new DeltaTable(tableId, schema, properties);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown property")) {
    log.error("Unsupported key in table properties: {}", e.getMessage());
  }
}

When it happens

Trigger: Supplying any table property key that is not 'version', 'timestamp', 'hadoop_config', or 'hadoopConfig' (and does not start with a beam_write/beam_read prefix) when constructing or validating a DeltaTable.

Common situations: Typo like 'timeStamp' handled? No — actually case-insensitive; real mistakes are misspellings like 'verssion', camelCase variants of keys without exact match like 'hadoopConf', or properties copied from other table providers.

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 Beam read property: {key}
• 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/bbb027bf977c38d8. Report an issue: GitHub.