jax-ml/jax · error · TypeError

new string config value must be of type str, got {new_val} o

Error message

new string config value must be of type str, got {new_val} of type {type(new_val)}.

What it means

The validator inside string_state (invoked by the flag's parser when a value is set) requires new values to be str. Non-str values (Path, bytes, Enum, None) raise this TypeError.

Source

Thrown at jax/_src/config.py:814

    default: string, a default value for the option.
    help: string, used to populate the flag help information as well as the
      docstring of the returned context manager.
    update_global_hook: an optional callback that is called with the updated
      value of the global state when it is altered or set initially.
    update_thread_local_hook: an optional callback that is called with the
      updated value of the thread-local state when it is altered or set
      initially.

  Returns:
    A contextmanager to control the thread-local state value.
  """
  if not isinstance(default, str):
    raise TypeError(f"Default value must be of type str, got {default} "
                    f"of type {getattr(type(default), '__name__', type(default))}")

  def validator(new_val):
    if not isinstance(new_val, str):
      raise TypeError('new string config value must be of type str,'
                       f' got {new_val} of type {type(new_val)}.')

  return string_or_object_state(
      name, default, help,
      update_global_hook=update_global_hook,
      update_thread_local_hook=update_thread_local_hook,
      validator=validator)


def optional_string_state(
    name: str,
    default: str | None,
    help: str,
    *,
    update_global_hook: Callable[[str], None] | None = None,
    update_thread_local_hook: Callable[[str | None], None] | None = None,
    include_in_trace_context: bool = False,
) -> State[str | None]:

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Convert with str(value) before setting
For Enum, pass SomeEnum.FOO.value

Example fix

// before
with jax.my_flag(BASE_DIR / 'cache'):
    ...
// after
with jax.my_flag(str(BASE_DIR / 'cache')):
    ...

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(new_val, str):
    new_val = str(new_val)

Type guard

def as_str(v) -> str:
    return v if isinstance(v, str) else str(v)

Try / catch

try:
    with my_flag(v):
        ...
except TypeError:
    with my_flag(str(v)):
        ...

Prevention

Convert Path and Enum (.value) objects before passing to string flags
Keep a thin wrapper for flag setting that enforces str types

When it happens

Trigger: with my_flag(Path('/tmp')): or jax.config.update('jax_my_flag', SomeEnum.FOO).

Common situations: Passing pathlib.Path objects or Enum members to a string config flag, common in path-handling or plugin-selection code.

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/ec6de7093a413d02. Report an issue: GitHub.