{"record":{"id":"646665e15466a236","repo":"apache/beam","slug":"expecting-exactly-one-field-found-field-names","errorCode":null,"errorMessage":"Expecting exactly one field, found {field_names}","messagePattern":"Expecting exactly one field, found (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_io.py","lineNumber":287,"sourceCode":"    beam_schema = json_utils.json_schema_to_beam_schema(schema)\n    return beam_schema, RowCoder(beam_schema).decode\n  else:\n    raise ValueError(f'Unknown format: {format}')\n\n\ndef _create_formatter(\n    format, schema: Any,\n    beam_schema: schema_pb2.Schema) -> Callable[[beam.Row], bytes]:\n\n  if format.islower():\n    format = format.upper()\n\n  if format == 'RAW':\n    if schema:\n      raise ValueError('RAW format does not take a schema')\n    field_names = [field.name for field in beam_schema.fields]\n    if len(field_names) != 1:\n      raise ValueError(f'Expecting exactly one field, found {field_names}')\n\n    def convert_to_bytes(row):\n      output = getattr(row, field_names[0])\n      if isinstance(output, bytes):\n        return output\n      elif isinstance(output, str):\n        return output.encode('utf-8')\n      else:\n        raise ValueError(\n            f\"Cannot encode payload for WriteToPubSub. \"\n            f\"Expected valid string or bytes object, \"\n            f\"got {repr(output)} of type {type(output)}.\")\n\n    return convert_to_bytes\n  elif format == 'JSON':\n    return json_utils.json_formater(beam_schema)\n  elif format == 'AVRO':\n    avro_schema = schema or avroio.beam_schema_to_avro_schema(beam_schema)","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_io.py#L269-L305","documentation":"In Apache Beam YAML's write_to_pubsub, the RAW format sends only a single field of each row as the raw Pub/Sub message payload. _create_formatter raises this ValueError when the beam schema does not have exactly one field, listing the fields it actually found.","triggerScenarios":"Calling write_to_pubsub with format='RAW' and a schema whose beam_schema has zero or multiple fields (e.g. a two-column row schema).","commonSituations":"Users configure RAW Pub/Sub output but forget RAW only supports single-field payloads; often the schema still carries id+value or attribute columns instead of a lone bytes/str field.","solutions":["Change format to JSON or PROTO if you need multi-field payloads","Ensure the input schema has exactly one field (bytes or str) whose value is the raw payload","Move extra fields into Pub/Sub attributes instead of the payload"],"exampleFix":"// before\nformat: RAW, schema: {id: STRING, payload: BYTES}\n// after\nformat: RAW, schema: {payload: BYTES}","handlingStrategy":"validation","validationCode":"names = [f.name for f in schema.fields]\nif len(names) != 1:\n    raise ValueError(f'RAW format needs exactly one field, got {names}')","typeGuard":"def is_single_field_schema(schema):\n    return schema is not None and len(schema.fields) == 1","tryCatchPattern":null,"preventionTips":["Reserve RAW format for single-field bytes/str schemas","Use JSON format for multi-field payloads","Document schema shape next to the sink config"],"tags":["python","apache-beam","pubsub","schema"],"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"}