apache/beam · error · ValueError

WriteToTFRecord requires an input schema with exactly one…

Error message

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

What it means

Like 4127 but for the case where the schema resolved successfully yet contains more (or zero) than one field. TFRecord holds a single raw value per record, so the wrapper raises listing the offending field names.

Solutions

Reduce input schema to one field containing exactly the bytes to write
Serialize the row yourself (e.g. to JSON string) into a single field before writing
Choose WriteToJson or another multi-field-capable sink

Example fix

// before
beam.Row(name='x', value=1) -> write_to_tfrecord
// after
beam.Row(data=json.dumps({'name':'x','value':1}).encode()) -> write_to_tfrecord

Defensive patterns

Strategy: validation

Validate before calling

names = [n for n, _ in schemas.named_fields_from_element_type(pcoll.element_type)]
if len(names) != 1:
    raise ValueError(f'TFRecord needs exactly one field, got {names}')

Try / catch

try:
    pcoll | yaml_io.write_to_tfrecord(...)
except ValueError as e:
    if 'exactly one field' in str(e):
        pcoll = pcoll | beam.Map(lambda r: beam.Row(data=json.dumps(r._as_dict()).encode()))

Prevention

Serialize multi-field rows into one bytes/str field first
Choose a different sink when data has multiple columns
Validate schema cardinality in pipeline construction tests

When it happens

Trigger: write_to_tfrecord given a schema with 2+ named fields, e.g. beam.Row(a=..., b=...).

Common situations: Users expect TFRecord to serialize whole rows; it only writes the sole field's value. Multi-field rows need JSON/protobuf-style sinks instead.

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

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

Appendix: source

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

      is '-SSSSS-of-NNNNN' if None is passed as the shard_name_template.
    compression_type: Used to handle compressed output files. Typical value
      is CompressionTypes.AUTO, in which case the file_path's extension will
      be used to detect the compression.

  Returns:
    A WriteToTFRecord transform object.
  """
  try:
    field_names = [
        name for name, _ in schemas.named_fields_from_element_type(
            pcoll.element_type)
    ]
  except Exception as exn:
    raise ValueError(
        "WriteToTFRecord requires an input schema with exactly one field."
    ) from exn
  if len(field_names) != 1:
    raise ValueError(
        "WriteToTFRecord requires an input schema with exactly one field,got %s"
        % field_names)
  sole_field_name, = field_names

  return pcoll | beam.Map(
      lambda x: getattr(x, sole_field_name)) | WriteToTFRecord(
          file_path_prefix=file_path_prefix,
          coder=coder,
          file_name_suffix=file_name_suffix,
          num_shards=num_shards,
          shard_name_template=shard_name_template,
          compression_type=getattr(CompressionTypes, compression_type))


@beam.ptransform_fn
@yaml_errors.maybe_with_exception_handling_transform_fn
def read_from_mongodb(
    root,

View on GitHub (pinned to 12126d8942)