apache/beam · error · IllegalArgumentException

Table must be specified to read with partitions.

Error message

Table must be specified to read with partitions.

What it means

Partitioned reads (withPartitionColumn) in Beam JDBC split the scan by ranges over a table column, which only works against a table, not an arbitrary query. If partitionColumn is set but location (table) is not, validate() throws this IllegalArgumentException.

Solutions

1. Replace the query with setLocation(tableName) and keep the partition column.
2. If you need partitioned query-style reads, drop partitionColumn and rely on the query as-is.
3. Optionally combine table + readQuery filtering capabilities the provider supports, keeping location set.

Example fix

// before
builder().setReadQuery("SELECT * FROM orders").setPartitionColumn("order_id")
// after
builder().setLocation("orders").setPartitionColumn("order_id")

if (hasText(config.getPartitionColumn()) && !hasText(config.getLocation())) {
  throw new IllegalArgumentException("partitionColumn requires location (table) to be set");
}

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if ("Table must be specified to read with partitions.".equals(e.getMessage())) {
    throw new IllegalStateException("Switch from readQuery to location(table) to enable partitioned reads", e);
  }
  throw e;
}

When it happens

Trigger: Building the transform with setPartitionColumn("id") while leaving location empty and supplying a readQuery (or nothing) instead of a table.

Common situations: Users attempt to speed up a slow custom query by adding a partition column, not realizing partitioning requires the table form.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Either Query or Table must be specified.
• If JDBC type is not specified, then Driver Class Name and…
• JDBC type must be one of
• JDBC URL cannot be blank
• One of JDBC Driver class name or JDBC type must be…

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

Appendix: source

Thrown at sdks/java/io/jdbc/src/main/java/org/apache/beam/sdk/io/jdbc/JdbcReadSchemaTransformProvider.java:439

          && !JDBC_DRIVER_MAP.containsKey(Objects.requireNonNull(jdbcType).toLowerCase())) {
        throw new IllegalArgumentException("JDBC type must be one of " + JDBC_DRIVER_MAP.keySet());
      }

      boolean readQueryPresent = (getReadQuery() != null && !"".equals(getReadQuery()));
      boolean locationPresent = (getLocation() != null && !"".equals(getLocation()));
      boolean partitionColumnPresent =
          (getPartitionColumn() != null && !"".equals(getPartitionColumn()));

      // If you specify a readQuery, it is to be used instead of a table.
      if (readQueryPresent && locationPresent) {
        throw new IllegalArgumentException("Query and Table are mutually exclusive configurations");
      }
      if (!readQueryPresent && !locationPresent) {
        throw new IllegalArgumentException("Either Query or Table must be specified.");
      }
      // Reading with partitions only supports table argument.
      if (partitionColumnPresent && !locationPresent) {
        throw new IllegalArgumentException("Table must be specified to read with partitions.");
      }
    }

    public static Builder builder() {
      return new AutoValue_JdbcReadSchemaTransformProvider_JdbcReadSchemaTransformConfiguration
          .Builder();
    }

    public abstract Builder toBuilder();

    @AutoValue.Builder
    public abstract static class Builder {
      public abstract Builder setDriverClassName(String value);

      public abstract Builder setJdbcType(String value);

      public abstract Builder setJdbcUrl(String value);

View on GitHub (pinned to 12126d8942)