apache/beam · error · ValueError

TableFieldsQueryConfig must provide non-empty…

Error message

TableFieldsQueryConfig must provide non-empty where_clause_fields

What it means

TableFieldsQueryConfig.__post_init__ also requires where_clause_fields to be non-empty, since the templated WHERE clause needs named fields to bind row values to query parameters. An empty list/None triggers this ValueError.

Solutions

Pass a non-empty list of field names matching the placeholders in where_clause_template
Ensure the fields exist on the enrichment input rows
Fall back to CustomQueryConfig if the query has no parameterized fields

Example fix

// before
TableFieldsQueryConfig(table_id='users', where_clause_template='WHERE id = :id', where_clause_fields=[])
// after
TableFieldsQueryConfig(table_id='users', where_clause_template='WHERE id = :id', where_clause_fields=['id'])

Defensive patterns

Strategy: validation

Validate before calling

def make_table_fields(table_id, tmpl, fields):
    if not fields or not isinstance(fields, list):
        raise ValueError('where_clause_fields must be a non-empty list')
    return TableFieldsQueryConfig(table_id, tmpl, fields)

Try / catch

try:
    cfg = TableFieldsQueryConfig(**raw)
except ValueError as e:
    raise ValueError('where_clause_fields must be non-empty') from e

Prevention

Ensure every :placeholder in the template has a matching field entry
Validate that listed fields exist on input rows
Avoid dynamically derived field lists that can silently be empty

When it happens

Trigger: TableFieldsQueryConfig(table_id='t', where_clause_template='WHERE id = :id', where_clause_fields=[]) or None.

Common situations: Declaring a WHERE template with placeholders but forgetting to list the corresponding fields; dynamically computed field lists that come back empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/cloudsql.py:69

    if not self.query_fn:
      raise ValueError("CustomQueryConfig must provide a valid query_fn")


@dataclass
class TableFieldsQueryConfig:
  """Configuration for using table name, where clause, and field names."""
  table_id: str
  where_clause_template: str
  where_clause_fields: list[str]

  def __post_init__(self):
    if not self.table_id or not self.where_clause_template:
      raise ValueError(
          "TableFieldsQueryConfig must provide table_id and " +
          "where_clause_template")

    if not self.where_clause_fields:
      raise ValueError(
          "TableFieldsQueryConfig must provide non-empty " +
          "where_clause_fields")


@dataclass
class TableFunctionQueryConfig:
  """Configuration for using table name, where clause, and a value function."""
  table_id: str
  where_clause_template: str
  where_clause_value_fn: ConditionValueFn

  def __post_init__(self):
    if not self.table_id or not self.where_clause_template:
      raise ValueError(
          "TableFunctionQueryConfig must provide table_id and " +
          "where_clause_template")

    if not self.where_clause_value_fn:

View on GitHub (pinned to 12126d8942)