jax-ml/jax · error · ValueError

invalid truth value {val!r} for environment {varname!r}

Error message

invalid truth value {val!r} for environment {varname!r}

What it means

JAX boolean config flags (e.g. JAX_ENABLE_X64, JAX_DEBUG_NANS) accept only a fixed set of truthy/falsy string spellings: y/yes/t/true/on/1 and n/no/f/false/off/0 (case-insensitive). bool_env parses the environment variable at import/config-definition time and raises ValueError for anything else, since there is no unambiguous interpretation.

Source

Thrown at jax/_src/config.py:60

def bool_env(varname: str, default: bool) -> bool:
  """Read an environment variable and interpret it as a boolean.

  True values are (case insensitive): 'y', 'yes', 't', 'true', 'on', and '1';
  false values are 'n', 'no', 'f', 'false', 'off', and '0'.

  Args:
    varname: the name of the variable
    default: the default boolean value
  Raises: ValueError if the environment variable is anything else.
  """
  val = os.getenv(varname, str(default))
  val = val.lower()
  if val in ('y', 'yes', 't', 'true', 'on', '1'):
    return True
  elif val in ('n', 'no', 'f', 'false', 'off', '0'):
    return False
  else:
    raise ValueError(f"invalid truth value {val!r} for environment {varname!r}")

def int_env(varname: str, default: int) -> int:
  """Read an environment variable and interpret it as an integer."""
  return int(os.getenv(varname, str(default)))


class ValueHolder[ValueType](Protocol):
  """A holder for a configuration value.

  There are two kinds of value holders: ``Flag``, which is assigned exactly
  once and never modified after; and ``State``, which can be changed locally
  within a thread via a context manager.
  """

  value: ValueType

  def _set(self, value: ValueType) -> None: ...

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Correct the value to one of: y/yes/t/true/on/1 or n/no/f/false/off/0 (case-insensitive)
2. Strip quotes and whitespace when exporting in Dockerfiles/shell: ENV JAX_ENABLE_X64=true (no quotes)
3. Audit with: env | grep JAX_ to find malformed values before importing jax

Example fix

# before
ENV JAX_ENABLE_X64="true"   # Dockerfile: literal quotes become part of the value
# after
ENV JAX_ENABLE_X64=true

import os, re

TRUTHY = {'y','yes','t','true','on','1'}
FALSY = {'n','no','f','false','off','0'}

def check_jax_bool_envs():
    for k, v in os.environ.items():
        if k.startswith('JAX_') and re.fullmatch(r'.*(TRUE|FALSE|ENABLE|DEBUG|DISABLE|ON|OFF).*', k):
            s = v.strip().lower()
            if s not in TRUTHY | FALSY:
                raise ValueError(f'{k}={v!r} is not a valid JAX bool')

When it happens

Trigger: Setting an env var like JAX_ENABLE_X64=YES PLEASE, JAX_DEBUG_NANS=enable, JAX_64BIT=2, or with a trailing space/quote, then importing jax or defining a new bool config option.

Common situations: Typos in CI environment matrices ('ture', 'flase'), values copied from docs with quotes (JAX_ENABLE_X64="true" in a Dockerfile where quotes are literal), or scripts writing 0/1 plus whitespace.

Related errors

• Invalid value "{default}" for JAX flag {name}
• Invalid value "{default_str}" for JAX flag {name}
• Invalid value "{default_env}" for JAX flag {name}
• Unrecognized config option: {name}
• For flags with a corresponding contextmanager, read their va

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