{"record":{"id":"d4143651ae6287a2","repo":"apache/beam","slug":"writetotext-requires-an-input-schema-with-exactly-one-field","errorCode":null,"errorMessage":"WriteToText requires an input schema with exactly one field.","messagePattern":"WriteToText requires an input schema with exactly one field\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_io.py","lineNumber":91,"sourceCode":"\n\n@beam.ptransform_fn\ndef write_to_text(pcoll, path: str):\n  \"\"\"Writes a PCollection to a (set of) text files(s).\n\n  The input must be a PCollection whose schema has exactly one field.\n\n  Args:\n      path (str): The file path to write to. The files written will\n        begin with this prefix, followed by a shard identifier.\n  \"\"\"\n  try:\n    field_names = [\n        name for name, _ in schemas.named_fields_from_element_type(\n            pcoll.element_type)\n    ]\n  except Exception as exn:\n    raise ValueError(\n        \"WriteToText requires an input schema with exactly one field.\") from exn\n  if len(field_names) != 1:\n    raise ValueError(\n        \"WriteToText requires an input schema with exactly one field, got %s\" %\n        field_names)\n  sole_field_name, = field_names\n  return pcoll | beam.Map(\n      lambda x: str(getattr(x, sole_field_name))) | beam.io.WriteToText(path)\n\n\ndef read_from_bigquery(\n    *,\n    table: Optional[str] = None,\n    query: Optional[str] = None,\n    row_restriction: Optional[str] = None,\n    fields: Optional[Iterable[str]] = None,\n    schema: Optional[Any] = None):\n  \"\"\"Reads data from BigQuery.","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_io.py#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the input PCollection has a declared Beam schema (e.g. pass through a transform that sets element_type/schema).","Project exactly one field upstream (e.g. a Map selecting the field) before writing.","Convert the data explicitly with a schema-aware transform so named_fields_from_element_type succeeds."],"exampleFix":"// before: writing rows with multiple/unspecified fields\n- type: WriteToText\n  input: my_rows\n// after: project a single typed field first\n- type: Map\n  input: my_rows\n  fn: \"lambda row: row.message\"","handlingStrategy":"validation","validationCode":"from apache_beam import schemas\nfields = schemas.named_fields_from_element_type(pcoll.element_type)  # raises if no schema\nassert len(list(fields)) == 1, \"write_to_text needs exactly one schema field\"","typeGuard":null,"tryCatchPattern":"try:\n    write_to_text(pcoll, path)\nexcept ValueError as e:\n    if 'exactly one field' in str(e):\n        pcoll = pcoll | beam.Map(lambda r: r.chosen_field)","preventionTips":["Keep schemas attached through the pipeline (avoid untyped Map/dict outputs before sinks).","Project to one field before WriteToText in the YAML spec.","Test pipeline element types with beam.Row / SchemaAware transforms in unit tests."],"tags":["python","apache-beam","yaml","schema","io"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}