apache/beam · error · TypeError

Unexpected type of id_or_name

Error message

Unexpected type of id_or_name: %s

What it means

The IdOrName helper for Datastore keys accepts only a str (entity name) or an int (numeric auto-ID). Passing any other type makes it impossible to tell whether the value should populate the key's name or id field, so __init__ raises TypeError immediately.

Solutions

1. Convert the value: pass int(id_or_name) if it represents a numeric Datastore ID, or str(id_or_name) if it is a key name.
2. Check that upstream data (JSON, CSV, ValueProvider) yields the correct type and cast at the boundary.
3. For ambiguous numeric strings, decide explicitly whether they are IDs or names and wrap with int() or keep as str accordingly.

Example fix

// before
key = Key(('Project', IdOrName(raw_id)))  # raw_id = '12345' from JSON
// after
key = Key(('Project', IdOrName(int(raw_id))))  # numeric ID
# or, if it is a name:
key = Key(('Project', IdOrName(str(raw_id))))

def to_id_or_name(v):
    if isinstance(v, bool):
        raise TypeError('bool is not a valid Datastore id_or_name')
    if isinstance(v, int):
        return IdOrName(v)
    if isinstance(v, str):
        return IdOrName(v)
    raise TypeError(f'id_or_name must be str or int, got {type(v)}')

def is_id_or_name(v):
    return isinstance(v, (str, int)) and not isinstance(v, bool)

try:
    component = IdOrName(raw)
except TypeError as e:
    component = IdOrName(str(raw))  # or int(raw) if numeric
    logging.warning('Coerced id_or_name: %s', e)

When it happens

Trigger: Constructing IdOrName with a value that is neither str nor int, e.g. IdOrName(12.5), IdOrName(None), IdOrName(b'abc'), or a key component built from an untyped config/JSON value.

Common situations: Datastore IDs read back from JSON or CSV arrive as strings that are actually numeric, or floats parsed from numeric columns; developers pass them straight into IdOrName without coercing to int.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A cluster_identifier should be Optional[Union[str…
• Cannot get a type descriptor for
• Cannot interpret as Duration.
• CombineGlobally can be used only with combineFn objects…
• database_config must be VectorDatabaseWriteConfig, got

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

Appendix: source

Thrown at sdks/python/apache_beam/io/gcp/datastore/v1new/query_splitter.py:145

  return scatter_query


class IdOrName(object):
  """Represents an ID or name of a Datastore key,

   Implements sort ordering: by ID, then by name, keys with IDs before those
   with names.
   """
  def __init__(self, id_or_name):
    self.id_or_name = id_or_name
    if isinstance(id_or_name, str):
      self.id = None
      self.name = id_or_name
    elif isinstance(id_or_name, int):
      self.id = id_or_name
      self.name = None
    else:
      raise TypeError('Unexpected type of id_or_name: %s' % id_or_name)

  def __lt__(self, other):
    if not isinstance(other, IdOrName):
      return super().__lt__(other)

    if self.id is not None:
      if other.id is None:
        return True
      else:
        return self.id < other.id

    if other.id is not None:
      return False

    return self.name < other.name

  def __eq__(self, other):
    if not isinstance(other, IdOrName):

View on GitHub (pinned to 12126d8942)