apache/beam · error · IllegalArgumentException

Configuration must provide a query string.

Error message

Configuration must provide a query string.

What it means

The Beam SQL SchemaTransform provider reads the 'query' key from its configuration map; if it is absent or null, expansion cannot build a SqlTransform, so it throws IllegalArgumentException with this message. It is an upfront config validation guard in SqlTransformSchemaTransformProvider.expand.

Solutions

1. Add a non-null 'query' entry to the transform configuration.
2. Validate config keys before submitting the pipeline (check for 'query' presence).
3. If building config from YAML, confirm the field name matches 'query' exactly.

Example fix

// before
Map<String, Object> config = Map.of("dialect", "calcite");
// after
Map<String, Object> config = Map.of(
    "query", "SELECT * FROM pcollection",
    "dialect", "calcite");

if (config == null || !config.containsKey("query") || config.get("query") == null || ((String) config.get("query")).isEmpty()) {
  throw new IllegalArgumentException("Transform config must include a non-empty 'query' string");
}

When it happens

Trigger: Calling SqlTransformSchemaTransformProvider.expand (via output()/testFailedExpression) with a configuration map that omits the 'query' key or sets it to null.

Common situations: Pipeline configs built programmatically or from YAML that forget the SQL statement; serialization round-trips dropping the config field; mistyping the key (e.g. 'sql' instead of 'query').

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• A 'datagen' table requires either 'rows-per-second' (for…
• Analytics Function [ ] is not supported
• Beam write property ' ' is not supported. Writing to Delta…
• Bigtable location must be in the following format…
• Cannot create UDF from method: method

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

Appendix: source

Thrown at sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/SqlTransformSchemaTransformProvider.java:170

  }

  static class SqlSchemaTransform extends SchemaTransform {
    final Row config;

    public SqlSchemaTransform(Row config) {
      this.config = config;
    }

    @Override
    public PCollectionRowTuple expand(PCollectionRowTuple input) {

      // Start with the query. In theory the exception can't be thrown, but all this nullness
      // stuff
      // isn't actually smart enough to know that. Could just cop and suppress that warning, but
      // doing it the hard way for some reason.
      String queryString = config.getString("query");
      if (queryString == null) {
        throw new IllegalArgumentException("Configuration must provide a query string.");
      }
      SqlTransform transform = SqlTransform.query(queryString);

      // Allow setting the query planner class via the dialect name.
      EnumerationType.Value dialect =
          config.getLogicalTypeValue("dialect", EnumerationType.Value.class);
      if (dialect != null) {
        Class<? extends QueryPlanner> queryPlannerClass =
            QUERY_PLANNERS.get(QUERY_ENUMERATION.toString(dialect));
        if (queryPlannerClass != null) {
          transform = transform.withQueryPlannerClass(queryPlannerClass);
        }
      }

      // Add any DDL strings
      String ddl = config.getString("ddl");
      if (ddl != null) {
        transform = transform.withDdlString(ddl);

View on GitHub (pinned to 12126d8942)