apache/beam · error · ValueError

TableFieldsQueryConfig must provide table_id and…

Error message

TableFieldsQueryConfig must provide table_id and where_clause_template

What it means

TableFieldsQueryConfig.__post_init__ requires both table_id and where_clause_template; if either is missing or empty a ValueError is raised. Without these, the handler cannot build the parameterized SQL query for Cloud SQL enrichment.

Solutions

Provide both table_id and a non-empty where_clause_template string
Validate your config source (YAML/env) before constructing the dataclass
Use CustomQueryConfig if you'd rather write the full query yourself

Example fix

// before
TableFieldsQueryConfig(table_id='', where_clause_template=None, where_clause_fields=['id'])
// 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):
    assert table_id, 'table_id required'
    assert tmpl, 'where_clause_template required'
    assert fields, 'where_clause_fields required'
    return TableFieldsQueryConfig(table_id, tmpl, fields)

Try / catch

try:
    cfg = TableFieldsQueryConfig(**raw)
except ValueError as e:
    raise ValueError(f'invalid TableFieldsQueryConfig: {e}') from e

Prevention

Validate YAML/env config for empty strings before constructing configs
Keep table_id and template together in a single config source
Add unit tests constructing each config variant

When it happens

Trigger: Constructing TableFieldsQueryConfig(table_id='', where_clause_template='WHERE x', ...) or omitting either required dataclass field (None/empty string).

Common situations: Filling in fields from environment/config where values end up empty strings; forgetting to template the WHERE clause when switching from CustomQueryConfig.

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/4177ba0b1c2c7792. Report an issue: GitHub.

Appendix: source

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

class CustomQueryConfig:
  """Configuration for using a custom query function."""
  query_fn: QueryFn

  def __post_init__(self):
    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:

View on GitHub (pinned to 12126d8942)