apache/beam · error · ValueError

WriteToText requires an input schema with exactly one field,

Error message

WriteToText requires an input schema with exactly one field, got %s

What it means

After successfully extracting field names from the input schema, write_to_text checks that exactly one field exists, since it writes str(getattr(row, field)) as each output line. If the input schema has zero or multiple fields, it raises ValueError including the actual field name list.

Source

Thrown at sdks/python/apache_beam/yaml/yaml_io.py:94

def write_to_text(pcoll, path: str):
  """Writes a PCollection to a (set of) text files(s).

  The input must be a PCollection whose schema has exactly one field.

  Args:
      path (str): The file path to write to. The files written will
        begin with this prefix, followed by a shard identifier.
  """
  try:
    field_names = [
        name for name, _ in schemas.named_fields_from_element_type(
            pcoll.element_type)
    ]
  except Exception as exn:
    raise ValueError(
        "WriteToText requires an input schema with exactly one field.") from exn
  if len(field_names) != 1:
    raise ValueError(
        "WriteToText requires an input schema with exactly one field, got %s" %
        field_names)
  sole_field_name, = field_names
  return pcoll | beam.Map(
      lambda x: str(getattr(x, sole_field_name))) | beam.io.WriteToText(path)


def read_from_bigquery(
    *,
    table: Optional[str] = None,
    query: Optional[str] = None,
    row_restriction: Optional[str] = None,
    fields: Optional[Iterable[str]] = None,
    schema: Optional[Any] = None):
  """Reads data from BigQuery.

  Exactly one of table or query must be set.
  If query is set, neither row_restriction nor fields should be set.

View on GitHub (pinned to 12126d8942)

Solutions

1. Add a Map/Select step upstream to project exactly one field before write_to_text.
2. Concatenate fields into a single string field, then write that.
3. Use a different sink (WriteToJson/WriteCsv) if multiple fields are needed.

Example fix

// before
- type: WriteToText
  input: parsed  # schema: {name, age}
// after
- type: Map
  input: parsed
  fn: "lambda row: row.name"
- type: WriteToText
  input: mapped

from apache_beam import schemas
names = [n for n, _ in schemas.named_fields_from_element_type(pcoll.element_type)]
assert len(names) == 1, f"WriteToText got fields {names}; project to exactly one first"

try:
    write_to_text(pcoll, path)
except ValueError as e:
    if 'got [' in str(e):
        raise ValueError("Add a Map/Select upstream to emit a single field before WriteToText") from e

When it happens

Trigger: Calling write_to_text on a schema'd PCollection with len(field_names) != 1 — e.g. a two-field schema like {user_id, message} — the wrapper cannot guess which field to serialize.

Common situations: Writing query/parse results that naturally have several columns directly to text; forgetting to reduce to one field before the sink.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• WriteToText requires an input schema with exactly one field.
• An explicit schema is required to write non-schema'd PCollec
• A schema is required to write non-schema'd data.
• Unrecognized type_info: {type_info!r}
• f"Mapping destinations {missing} for {type} are not in the u

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