apache/beam · error · TypeError

Cannot convert from a JSON value.

Error message

Cannot convert %s from a JSON value.

What it means

apache_beam.internal.gcp.json_value.from_json_value converts extra_types.JsonValue/JsonArray/JsonObject protobufs back into plain Python objects. If the value passed is not one of these recognized proto wrapper types (e.g. a raw primitive or a foreign proto message), the function cannot dispatch and raises TypeError with the repr of the value.

Solutions

1. Ensure the input is a extra_types.JsonValue/JsonArray/JsonObject proto, not a raw dict or string
2. If you have raw JSON, wrap it: extra_types.JsonValue(string_value=json.dumps(obj)) or use a JSON parser that produces JsonValue protos
3. Use json.loads on raw bytes/str instead of from_json_value, which is only for the proto representation

Example fix

// before
from apache_beam.internal.gcp.json_value import from_json_value
obj = from_json_value({'a': 1})  # TypeError
// after
import json
from apache_beam.internal.gcp import json_value
from apache_beam.portability.api import schema_pb2
jv = json_value.to_json_value({'a': 1})
obj = json_value.from_json_value(jv)

from apache_beam.portability.api import external_descriptors
from apache_beam.internal.gcp import json_value
isinstance(v, (json_value.extra_types.JsonValue, json_value.extra_types.JsonArray, json_value.extra_types.JsonObject))

from apache_beam.internal.gcp import json_value
def is_json_value(v):
    t = json_value.extra_types
    return isinstance(v, (t.JsonValue, t.JsonArray, t.JsonObject))

try:
    obj = from_json_value(v)
except TypeError:
    import json
    obj = json.loads(v)  # fallback for raw JSON payloads

When it happens

Trigger: Calling from_json_value(v) where v is not an instance of extra_types.JsonValue, JsonArray, or JsonObject — e.g. passing a raw Python dict, a string, or a different protobuf message type.

Common situations: Users receiving JSON responses and passing raw parsed dicts instead of the JsonValue proto; mixing up raw JSON strings with JsonValue objects when working with BigQuery/Beam internal APIs.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Cannot convert to a JSON value.
• Cannot get a type descriptor for
• A cluster_identifier should be Optional[Union[str…
• bad struct encoding
• can not be deserialized from Json

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

Appendix: source

Thrown at sdks/python/apache_beam/internal/gcp/json_value.py:165

    if v.string_value is not None:
      return v.string_value
    elif v.boolean_value is not None:
      return v.boolean_value
    elif v.integer_value is not None:
      return v.integer_value
    elif v.double_value is not None:
      return v.double_value
    elif v.array_value is not None:
      return from_json_value(v.array_value)
    elif v.object_value is not None:
      return from_json_value(v.object_value)
    elif v.is_null:
      return None
  elif isinstance(v, extra_types.JsonArray):
    return [from_json_value(e) for e in v.entries]
  elif isinstance(v, extra_types.JsonObject):
    return {p.key: from_json_value(p.value) for p in v.properties}
  raise TypeError('Cannot convert %s from a JSON value.' % repr(v))

View on GitHub (pinned to 12126d8942)