{"record":{"id":"553b2858a1022897","repo":"apache/beam","slug":"writetotfrecord-requires-an-input-schema-with-exactly-one","errorCode":null,"errorMessage":"WriteToTFRecord requires an input schema with exactly one field.","messagePattern":"WriteToTFRecord 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":759,"sourceCode":"      particular shard number, the upper-case letters 'S' and 'N' are\n      replaced with the 0-padded shard number and shard count respectively.\n      This argument can be '' in which case it behaves as if num_shards was\n      set to 1 and only one file will be generated. The default pattern used\n      is '-SSSSS-of-NNNNN' if None is passed as the shard_name_template.\n    compression_type: Used to handle compressed output files. Typical value\n      is CompressionTypes.AUTO, in which case the file_path's extension will\n      be used to detect the compression.\n\n  Returns:\n    A WriteToTFRecord transform object.\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        \"WriteToTFRecord requires an input schema with exactly one field.\"\n    ) from exn\n  if len(field_names) != 1:\n    raise ValueError(\n        \"WriteToTFRecord requires an input schema with exactly one field,got %s\"\n        % field_names)\n  sole_field_name, = field_names\n\n  return pcoll | beam.Map(\n      lambda x: getattr(x, sole_field_name)) | WriteToTFRecord(\n          file_path_prefix=file_path_prefix,\n          coder=coder,\n          file_name_suffix=file_name_suffix,\n          num_shards=num_shards,\n          shard_name_template=shard_name_template,\n          compression_type=getattr(CompressionTypes, compression_type))\n\n","sourceCodeStart":741,"sourceCodeEnd":777,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_io.py#L741-L777","documentation":"WriteToTFRecord writes raw bytes, so the YAML wrapper expects a one-field schema whose single value is the record content. When named_fields_from_element_type cannot resolve the element type (no/incompatible schema), it re-raises as this ValueError.","triggerScenarios":"Calling write_to_tfrecord on a PCollection whose element type has no named schema fields (untyped rows, non-schema elements), so schemas.named_fields_from_element_type throws.","commonSituations":"Passing plain dicts/bytes without a Beam schema; forgetting to apply as_json/as_dict schema typing upstream; using a Parse with no output schema.","solutions":["Ensure the input PCollection has a typed schema with exactly one field (e.g. via beam.Map(lambda x: beam.Row(data=x)))","Verify the element type is schema-aware before writing","Use a different sink (e.g. WriteToJson) for multi-field data"],"exampleFix":"// before\npcoll | yaml_io.write_to_tfrecord(file_pattern_prefix='out')  # untyped rows\n// after\npcoll | beam.Map(lambda x: beam.Row(data=x)) | yaml_io.write_to_tfrecord(file_pattern_prefix='out')","handlingStrategy":"validation","validationCode":"try:\n    names = [n for n, _ in schemas.named_fields_from_element_type(pcoll.element_type)]\nexcept Exception:\n    raise ValueError('Input must have a schema with exactly one field')","typeGuard":"def has_single_field_schema(pcoll):\n    try:\n        return len(schemas.named_fields_from_element_type(pcoll.element_type)) == 1\n    except Exception:\n        return False","tryCatchPattern":"try:\n    pcoll | yaml_io.write_to_tfrecord(...)\nexcept ValueError as e:\n    if 'exactly one field' in str(e):\n        pcoll = pcoll | beam.Map(lambda x: beam.Row(data=x))","preventionTips":["Always assign an explicit Beam schema to elements before TFRecord sinks","Write unit tests asserting element_type shape","Prefer JSON sink for structured rows"],"tags":["python","apache-beam","tfrecord","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-20T03:17:13.778Z"}