jax-ml/jax · error · TypeError

new enum value must be an instance of {enum_class}, got {new

Error message

new enum value must be an instance of {enum_class}, got {new_val} of type {type(new_val)}.

What it means

The parser for enum_class_state accepts either a str (converted via enum_class(new_val), which can itself raise ValueError for unknown strings) or an enum_class instance; any other type raises this TypeError when the flag is set.

Source

Thrown at jax/_src/config.py:649

  if not isinstance(default, enum_class):
    raise TypeError(
        f'Default value must be of type {enum_class}, got {default} '
        f"of type {getattr(type(default), '__name__', type(default))}"
    )
  name = name.lower()
  default_str = os.getenv(name.upper(), None)
  if default_str is not None:
    try:
      default = enum_class(default_str)
    except ValueError as e:
      raise ValueError(f"Invalid value \"{default_str}\" for JAX flag {name}") from e
  config._contextmanager_flags.add(name)

  def parser(new_val):
    if isinstance(new_val, str):
      return enum_class(new_val)
    if not isinstance(new_val, enum_class):
      raise TypeError(
          f'new enum value must be an instance of {enum_class}, got'
          f' {new_val} of type {type(new_val)}.'
      )
    if extra_validator is not None:
      extra_validator(new_val)
    return new_val

  s = State[EnumType](
      name,
      default,
      help,
      update_global_hook=update_global_hook,
      update_thread_local_hook=update_thread_local_hook,
      parser=parser,
      include_in_jit_key=include_in_jit_key,
      include_in_trace_context=include_in_trace_context,
  )
  config.add_option(

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Pass MyEnum.FOO or the exact string 'foo'
Convert deserialized data explicitly before setting the flag

Example fix

// before
with jax.my_flag(cfg['mode']):  # cfg loaded from YAML -> int 1
    ...
// after
with jax.my_flag(MyEnum(cfg['mode'])):
    ...

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(new_val, str):
    new_val = enum_class(new_val)
elif not isinstance(new_val, enum_class):
    raise TypeError(f'expected str or {enum_class.__name__}, got {type(new_val)}')

Type guard

def coerce_enum(v, cls):
    return cls(v) if isinstance(v, str) else v if isinstance(v, cls) else None

Try / catch

try:
    with my_flag(v):
        ...
except (TypeError, ValueError):
    with my_flag(DEFAULT_ENUM):
        ...

Prevention

Normalize deserialized (JSON/YAML) values to Enum members before setting flags
Never pass integer indices to enum flags

When it happens

Trigger: with my_flag(1): or jax.config.update('jax_my_flag', SomeObject()) — passing an int, None, or unrelated object.

Common situations: Passing a value parsed from JSON/YAML config that lost its Enum type (became a plain dict/str of the wrong shape), or an integer index meant to select a member.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/c3fea170e94571d1. Report an issue: GitHub.