apache/beam · error · ValueError

STRING format does not take a schema

Error message

STRING format does not take a schema

What it means

Analogous to RAW: the 'STRING' format in _create_parser decodes each Pub/Sub message as UTF-8 text into a single 'payload' string field, so no schema can be applied. Supplying one raises ValueError('STRING format does not take a schema').

Source

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

    schema: Any) -> tuple[schema_pb2.Schema, Callable[[bytes], beam.Row]]:

  format = format.upper()

  def _validate_schema():
    if not schema:
      raise ValueError(
          f'{format} format requires valid {format} schema to be passed to '
          f'schema parameter.')

  if format == 'RAW':
    if schema:
      raise ValueError('RAW format does not take a schema')
    return (
        schema_pb2.Schema(fields=[schemas.schema_field('payload', bytes)]),
        lambda payload: beam.Row(payload=payload))
  if format == 'STRING':
    if schema:
      raise ValueError('STRING format does not take a schema')
    return (
        schema_pb2.Schema(fields=[schemas.schema_field('payload', str)]),
        lambda payload: beam.Row(payload=payload.decode('utf-8')))
  elif format == 'JSON':
    _validate_schema()
    beam_schema = json_utils.json_schema_to_beam_schema(schema)
    return beam_schema, json_utils.json_parser(beam_schema, schema)
  elif format == 'AVRO':
    _validate_schema()
    beam_schema = avroio.avro_schema_to_beam_schema(schema)
    covert_to_row = avroio.avro_dict_to_beam_row(schema, beam_schema)
    return (
        beam_schema, lambda record: covert_to_row(
            fastavro.schemaless_reader(io.BytesIO(record), schema)))
  elif format == 'PROTO':
    _validate_schema()
    beam_schema = json_utils.json_schema_to_beam_schema(schema)
    return beam_schema, RowCoder(beam_schema).decode

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove the schema parameter when format is 'STRING'.
2. Switch to format 'JSON' (with the schema) if messages are structured JSON.
3. Validate the YAML config so format and schema are consistent.

Example fix

// before
- type: ReadFromPubSub
  format: STRING
  schema: '{...}'
// after
- type: ReadFromPubSub
  format: STRING

if fmt.upper() == 'STRING' and schema:
    raise ValueError("Drop 'schema' when format is STRING")

try:
    read_from_pubsub(format='STRING', schema=schema)
except ValueError as e:
    if 'STRING format does not take a schema' in str(e):
        schema = None

When it happens

Trigger: Calling read_from_pubsub with format='STRING' and schema set to a non-None/non-empty value.

Common situations: Leaving a JSON schema in the config after changing format from JSON to STRING; template configs that always include a schema field.

Related errors

• RAW format does not take a schema
• {format} format requires valid {format} schema to be passed
• Unknown format: {format}
• Only one of topic and subscription may be specified.
• Either data (%r) or attributes (%r) must be set.

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