apache/beam · error · TypeError

Only strings allowd as map keys when converting from JSON, f

Error message

Only strings allowd as map keys when converting from JSON, found {beam_type}

What it means

json_to_row converts parsed JSON values into Beam Rows following a Beam schema. For map-typed fields, JSON objects only support string keys, so if the Beam schema's map key type is not STRING, a TypeError is raised (note the message contains a typo: 'allowd'). The Beam schema is stricter than JSON allows.

Source

Thrown at sdks/python/apache_beam/yaml/json_utils.py:191

  if beam_type.nullable:
    non_null_type = schema_pb2.FieldType()
    non_null_type.CopyFrom(beam_type)
    non_null_type.nullable = False
    non_null_converter = json_to_row(non_null_type)
    return lambda value: None if value is None else non_null_converter(value)

  type_info = beam_type.WhichOneof("type_info")
  if type_info == "atomic_type":
    return lambda value: value
  elif type_info == "array_type":
    element_converter = json_to_row(beam_type.array_type.element_type)
    return lambda value: [element_converter(e) for e in value]
  elif type_info == "iterable_type":
    element_converter = json_to_row(beam_type.iterable_type.element_type)
    return lambda value: [element_converter(e) for e in value]
  elif type_info == "map_type":
    if beam_type.map_type.key_type.atomic_type != schema_pb2.STRING:
      raise TypeError(
          f'Only strings allowd as map keys when converting from JSON, '
          f'found {beam_type}')
    value_converter = json_to_row(beam_type.map_type.value_type)
    return lambda value: {k: value_converter(v) for (k, v) in value.items()}
  elif type_info == "row_type":
    field_nullable_status = {
        field.name: field.type.nullable
        for field in beam_type.row_type.schema.fields
    }

    converters = {
        field.name: json_to_row(field.type)
        for field in beam_type.row_type.schema.fields
    }

    def convert_row(value):
      kwargs = {}
      for name, convert in converters.items():

View on GitHub (pinned to 12126d8942)

Solutions

1. Change the schema so map key_type is string
2. Pre-convert non-string keys to strings before JSON conversion (e.g. stringify in an earlier step)
3. Use a row/array representation instead of a map if keys must be non-strings

Example fix

# before
schema: "map<integer, string> counts"
# after
schema: "map<string, string> counts"

from apache_beam.typehelp import schema_pb2
def assert_string_map_keys(beam_schema):
    for f in beam_schema.fields:
        t = f.type
        if t.WhichOneof('type_info') == 'map_type' and t.map_type.key_type.atomic_type != schema_pb2.STRING:
            raise TypeError(f'Field {f.name}: JSON maps require string keys')

def has_string_map_keys(beam_type) -> bool:
    if beam_type.WhichOneof('type_info') != 'map_type':
        return True
    return beam_type.map_type.key_type.atomic_type == schema_pb2.STRING

try:
    row = json_parser(beam_schema)(raw)
except TypeError as e:
    raise TypeError(f'Re-declare map keys as string in schema: {e}') from e

When it happens

Trigger: A Beam schema field with map_type whose key_type is int/bytes/etc., while feeding JSON input through json_to_row or a json_parser-based source (e.g. yaml transforms consuming JSON with a declared schema).

Common situations: Declaring a schema in pipeline YAML with map keys of integer/long and a JSON input source; converting between Avro/Parquet (int-keyed maps) and JSON within the same yaml pipeline.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Only strings allowd as map keys when converting to JSON, fou
• repeat(repeats=) value must be an int or a DeferredSeries (e
• Passing a deferred series to round() is not supported, pleas
• str.repeat(repeats=) value must be an int or a DeferredSerie
• Could not find code object with path: {code_object_identifie

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