apache/beam · error · ValueError

WriteToText requires an input schema with exactly one field.

Error message

WriteToText requires an input schema with exactly one field.

What it means

The Beam YAML write_to_text wrapper maps a single-field PCollection onto beam.io.WriteToText by extracting that one field as the line content. It first calls schemas.named_fields_from_element_type on the input element type; if the input has no usable schema (e.g. untyped Rows or a non-schema type), this call raises and the wrapper re-raises ValueError stating exactly one schema field is required.

Source

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

@beam.ptransform_fn
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.

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the input PCollection has a declared Beam schema (e.g. pass through a transform that sets element_type/schema).
2. Project exactly one field upstream (e.g. a Map selecting the field) before writing.
3. Convert the data explicitly with a schema-aware transform so named_fields_from_element_type succeeds.

Example fix

// before: writing rows with multiple/unspecified fields
- type: WriteToText
  input: my_rows
// after: project a single typed field first
- type: Map
  input: my_rows
  fn: "lambda row: row.message"

from apache_beam import schemas
fields = schemas.named_fields_from_element_type(pcoll.element_type)  # raises if no schema
assert len(list(fields)) == 1, "write_to_text needs exactly one schema field"

try:
    write_to_text(pcoll, path)
except ValueError as e:
    if 'exactly one field' in str(e):
        pcoll = pcoll | beam.Map(lambda r: r.chosen_field)

When it happens

Trigger: Passing a PCollection whose element_type has no extractable named schema fields to write_to_text — e.g. output of a transform that lost schema info, or an untyped/Any element type — so schemas.named_fields_from_element_type throws.

Common situations: Chaining write_to_text after transforms that return plain dicts/rows without a declared schema; using YAML LogForDynamics or custom Python transforms that drop the schema.

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