apache/beam · error · IllegalArgumentException

Unknown Beam read property

Error message

Unknown Beam read property: ${name}

What it means

IcebergTable currently supports no Beam-specific read properties. Any table property beginning with the 'beam_read_' prefix is rejected in the constructor with this IllegalArgumentException, because the read path consumes no configurable options.

Solutions

  1. Remove all beam_read_* properties from the table definition
  2. Configure the read via pipeline options or the Iceberg catalog config instead of table properties
  3. Check the Beam Iceberg documentation for supported configuration surfaces (none exist as table properties today)

Example fix

// before
CREATE EXTERNAL TABLE ... TBLPROPERTIES {'beam_read_concurrency':'8'}
// after
CREATE EXTERNAL TABLE ... -- no beam_read_* properties
Defensive patterns

Strategy: validation

Validate before calling

boolean hasReadProps = props.keySet().stream()
  .map(String::toLowerCase)
  .anyMatch(k -> k.startsWith("beam_read_"));
if (hasReadProps) throw new IllegalArgumentException("beam_read_* properties are not supported");

Try / catch

try { new IcebergTable(...); } catch (IllegalArgumentException e) { /* surface property cleanup instruction */ }

Prevention

When it happens

Trigger: Declaring a Beam SQL Iceberg table with any beam_read_* property (e.g. beam_read_streaming='true') in TBLPROPERTIES or the properties map.

Common situations: Guessing at read configuration knobs, copying options from other connectors, following outdated docs or blog posts that mention beam_read_ options for Iceberg.

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

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

Appendix: source

Thrown at sdks/java/extensions/sql/iceberg/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/iceberg/IcebergTable.java:88

  IcebergTable(String tableIdentifier, Table table, IcebergCatalogConfig catalogConfig) {
    super(table.getSchema());
    this.schema = table.getSchema();
    this.tableIdentifier = tableIdentifier;
    this.catalogConfig = catalogConfig;
    ObjectNode properties = table.getProperties();
    for (Map.Entry<String, JsonNode> property : properties.properties()) {
      String name = property.getKey().toLowerCase();
      if (name.startsWith(BEAM_WRITE_PROPERTY)) {
        String prop = name.substring(BEAM_WRITE_PROPERTY.length());
        if (prop.equalsIgnoreCase(TRIGGERING_FREQUENCY_FIELD)) {
          this.triggeringFrequency = property.getValue().asInt();
        } else {
          throw new IllegalArgumentException("Unknown Beam write property: " + name);
        }
      } else if (name.startsWith(BEAM_READ_PROPERTY)) {
        // none supported yet
        throw new IllegalArgumentException("Unknown Beam read property: " + name);
      }
    }

    this.partitionFields = table.getPartitionFields();
  }

  @Override
  public POutput buildIOWriter(PCollection<Row> input) {
    ImmutableMap.Builder<String, Object> configBuilder = ImmutableMap.builder();
    configBuilder.putAll(getBaseConfig());
    if (triggeringFrequency != null) {
      configBuilder.put(TRIGGERING_FREQUENCY_FIELD, triggeringFrequency);
    }
    if (partitionFields != null) {
      configBuilder.put("partition_fields", partitionFields);
    }
    return input.apply(Managed.write(Managed.ICEBERG).withConfig(configBuilder.build()));
  }

View on GitHub (pinned to 12126d8942)