apache/beam · error · TypeError

name is not a string

Error message

name is not a string

What it means

StateSpec.__init__ validates that the state cell name is a Python str. A TypeError is raised immediately at spec construction time because the name is used as a dictionary/registry key throughout the state machinery and must be a string.

Solutions

1. Pass a string as the name argument, e.g. StateSpec('running_sum', coder)
2. Check the argument order — name comes before coder
3. Coerce the variable with str(...) only if that preserves the intended identifier

Example fix

// before
spec = StateSpec(42, coders.StrUtf8Coder())
// after
spec = StateSpec('counter', coders.StrUtf8Coder())

if not isinstance(name, str):
    raise TypeError(f'StateSpec name must be str, got {type(name).__name__}')

def is_valid_state_name(name) -> bool:
    return isinstance(name, str)

try:
    spec = StateSpec(name, coder)
except TypeError as e:
    raise TypeError(f'bad StateSpec args (name={name!r}): {e}') from e

When it happens

Trigger: Calling StateSpec(42, coder), StateSpec(b'name', coder), StateSpec(None, coder), or otherwise passing a non-string as the first positional argument to StateSpec (or its subclasses like ReadModifyWriteStateSpec, CombiningValueStateSpec, BagStateSpec, SetStateSpec, TimerSpec-adjacent specs).

Common situations: Passing a variable that is accidentally an int/enum/bytes; f-string-free concatenation mistakes; confusing argument order and passing the coder first.

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

• coder is not of type Coder
• A context manager constructor (not a fully constructed…
• combine_fn must be provided
• Dependencies must be a list of strings, got
• DoFn %r has duplicate

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/userstate.py:52

from apache_beam.coders import coders
from apache_beam.portability import common_urns
from apache_beam.portability.api import beam_runner_api_pb2
from apache_beam.transforms.timeutil import TimeDomain
from apache_beam.utils import windowed_value
from apache_beam.utils.timestamp import Timestamp

if TYPE_CHECKING:
  from apache_beam.runners.pipeline_context import PipelineContext
  from apache_beam.transforms.core import DoFn

CallableT = TypeVar('CallableT', bound=Callable)


class StateSpec(object):
  """Specification for a user DoFn state cell."""
  def __init__(self, name: str, coder: Coder) -> None:
    if not isinstance(name, str):
      raise TypeError("name is not a string")
    if not isinstance(coder, Coder):
      raise TypeError("coder is not of type Coder")
    self.name = name
    self.coder = coder

  def __repr__(self) -> str:
    return '%s(%s)' % (self.__class__.__name__, self.name)

  def to_runner_api(
      self, context: 'PipelineContext') -> beam_runner_api_pb2.StateSpec:
    raise NotImplementedError


class ReadModifyWriteStateSpec(StateSpec):
  """Specification for a user DoFn value state cell.
     Read more about ReadModifyWriteState (ValueState) here:
     https://beam.apache.org/documentation/programming-guide/#valuestate
  """

View on GitHub (pinned to 12126d8942)