jax-ml/jax · error · ValueError

Invalid value "{default_env}" for JAX flag {name}

Error message

Invalid value "{default_env}" for JAX flag {name}

What it means

int_state reads the JAX_<FLAG> environment variable and calls int(default_env); if the string is not parseable as an integer, this ValueError is raised at jax import / flag definition.

Source

Thrown at jax/_src/config.py:711

      option (and absl flag). It is converted to uppercase to define the
      corresponding shell environment variable.
    default: optional int, default value.
    help: string, used to populate the flag help information as well as the
      docstring of the returned context manager.

  Returns:
    A contextmanager to control the thread-local state value.
  """
  if not isinstance(default, int):
    raise TypeError(f"Default value must be of type int, got {default} "
                    f"of type {getattr(type(default), '__name__', type(default))}")
  name = name.lower()
  default_env = os.getenv(name.upper())
  if default_env is not None:
    try:
      default = int(default_env)
    except ValueError:
      raise ValueError(f"Invalid value \"{default_env}\" for JAX flag {name}")
  config._contextmanager_flags.add(name)

  def parser(new_val):
    if new_val is not None and not isinstance(new_val, int):
      raise ValueError(f'new int config value must be None or of type int, '
                       f'got {new_val} of type {type(new_val)}')
    if new_val is not None and validator is not None:
      validator(new_val)
    return new_val

  s = State[int](name, default, help, update_global_hook,
                 update_thread_local_hook, parser,
                 include_in_jit_key=include_in_jit_key,
                 include_in_trace_context=include_in_trace_context)
  config.add_option(name, s, int, meta_args=[], meta_kwargs={"help": help})
  setattr(Config, name, property(lambda _: s.value))
  return s

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Use a plain integer string: export JAX_MY_FLAG=10000
2. Unset accidental empty values: unset JAX_MY_FLAG
3. Check for stray quotes/whitespace: echo "[$JAX_MY_FLAG]"

Example fix

# before
export JAX_MY_FLAG=1e6
# after
export JAX_MY_FLAG=1000000

raw = os.getenv('JAX_MY_FLAG')
if raw is not None:
    int(raw)  # fail fast with a clear message before importing jax

When it happens

Trigger: Exporting JAX_MY_FLAG=10_000, JAX_MY_FLAG=1e6, or JAX_MY_FLAG='' (empty string) — none parse via int().

Common situations: Shell scripts or CI setting numeric-looking env vars with commas, underscores, scientific notation, or accidentally empty values (e.g. `export JAX_MY_FLAG=$UNSET_VAR`).

Related errors

• Invalid value "{default}" for JAX flag {name}
• Invalid value "{default_str}" for JAX flag {name}
• new int config value must be None or of type int, got {new_v
• invalid truth value {val!r} for environment {varname!r}
• new enum value must be in {enum_values}, got {new_val} of ty

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