jax-ml/jax · error · Exception

Config option {name} already defined

Error message

Config option {name} already defined

What it means

When JAX (or user code) registers a new config option, add_option guards against double registration by raising a generic Exception. Duplicate names would make the flag's value ambiguous (two thread-local holders, one absl flag), so registration fails fast. This commonly fires when jax.config.config_with_absl or module-level define_*_state calls execute twice.

Source

Thrown at jax/_src/config.py:120

    if name in self._contextmanager_flags:
      raise AttributeError(
          "For flags with a corresponding contextmanager, read their value "
          f"via e.g. `config.{name}` rather than `config.FLAGS.{name}`.")
    return self._read(name)

  def _read(self, name):
    try:
      return self._value_holders[name].value
    except KeyError:
      raise AttributeError(f"Unrecognized config option: {name}")

  @property
  def values(self):
    return {name: holder.value for name, holder in self._value_holders.items()}

  def add_option(self, name, holder, opt_type, meta_args, meta_kwargs):
    if name in self._value_holders:
      raise Exception(f"Config option {name} already defined")
    self._value_holders[name] = holder
    self.meta[name] = (opt_type, meta_args, meta_kwargs)

  def config_with_absl(self):
    """Registers absl flags for the JAX configs.

    E.g., for each JAX config defined using bool_state(), this method
    registers an absl boolean flag, with the same name.

    This is the recommended method to call if you use `app.run(main)` and you
    need JAX flags.

    Examples:

    ```python
    from absl import app
    import jax
    ...

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Guard registration: if 'jax_my_flag' not in jax.config.values: jax.config.define_bool_state(...)
2. If the flag now exists in JAX core, drop your custom definition and use the built-in one
3. Move define_* calls to a single module-level location executed once

Example fix

# before
jax.config.define_bool_state('jax_my_flag', False, 'my flag')  # re-run cell -> Exception
# after
if 'jax_my_flag' not in jax.config.values:
    jax.config.define_bool_state('jax_my_flag', False, 'my flag')

import jax

def define_flag_once(name, default, help):
    if name not in jax.config.values:
        jax.config.define_bool_state(name, default, help)

define_flag_once('jax_my_flag', False, 'my flag')

When it happens

Trigger: Re-importing/re-executing a module that calls jax.config.define_bool_state('jax_my_flag', ...) without reloading; manually calling config_with_absl() twice; copy-pasting a define_* block into two modules with the same option name.

Common situations: Notebook re-running a cell that defines a custom flag; plugins/extensions registering a flag that core JAX already added in a newer version (name collision after upgrade).

Related errors

• invalid truth value {val!r} for environment {varname!r}
• Unrecognized config option: {name}
• For flags with a corresponding contextmanager, read their va
• bool() not supported for instances of type '{0}' (did you me
• Context manager for {state.__name__} config option requires

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