jax-ml/jax · error · ValueError

new string config value must be None or of type str, got {ne

Error message

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

What it means

The validator in optional_string_state (invoked via the parser when the flag is set) requires new values to be None or str; other types (int, Path, bytes, Enum) raise this ValueError.

Source

Thrown at jax/_src/config.py:859

    default: optional 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 default is not None and not isinstance(default, str):
    raise TypeError(f"Default value must be of type str or None, got {default} "
                    f"of type {getattr(type(default), '__name__', type(default))}")

  def validator(new_val):
    if new_val is not None and not isinstance(new_val, str):
      raise ValueError('new string config value must be None or 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,
      include_in_trace_context=include_in_trace_context)

def string_or_object_state(
    name: str,
    default: Any,
    help: str,
    *,
    update_global_hook: Callable[[Any], None] | None = None,
    update_thread_local_hook: Callable[[Any], None] | None = None,
    validator: Callable[[Any], None] | None = None,
    include_in_jit_key: bool = False,

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Wrap with str(): str(value) or pass None
Normalize config dataclasses so flag fields are already str|None

Example fix

// before
with jax.my_flag(out_dir):  # out_dir: Path | None
    ...
// after
with jax.my_flag(str(out_dir) if out_dir else None):
    ...

Defensive patterns

Strategy: validation

Validate before calling

if new_val is not None and not isinstance(new_val, str):
    new_val = str(new_val)

Type guard

def as_str_or_none(v):
    return None if v is None else (v if isinstance(v, str) else str(v))

Try / catch

try:
    with my_flag(v):
        ...
except ValueError:
    with my_flag(str(v) if v is not None else None):
        ...

Prevention

Convert Path objects at the boundary of your config layer
Annotate flag fields as str | None and validate with a schema loader

When it happens

Trigger: with my_flag(42):, with my_flag(Path('/x')):, or jax.config.update('jax_my_flag', b'bytes').

Common situations: Optional destination flags (cache dirs, dump paths) receiving Path objects or values from typed config loaders.

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