jax-ml/jax · error · ValueError

Unknown value for mode {mode}, must be one of: ('psd', 'stft

Error message

Unknown value for mode {mode}, must be one of: ('psd', 'stft')

What it means

_spectral_helper is the shared engine for csd/stft and dispatches on an internal mode string. Only 'psd' (power-spectral density path, used by csd) and 'stft' are recognized; this is an internal invariant, not a user-facing parameter.

Source

Thrown at jax/_src/scipy/signal.py:630

  return ext


def _spectral_helper(x: Array, y: ArrayLike | None, fs: ArrayLike = 1.0,
                     window: str = 'hann', nperseg: int | None = None,
                     noverlap: int | None = None, nfft: int | None = None,
                     detrend_type: bool | str | Callable[[Array], Array] = 'constant',
                     return_onesided: bool = True, scaling: str = 'density',
                     axis: int = -1, mode: str = 'psd', boundary: str | None = None,
                     padded: bool = False) -> tuple[Array, Array, Array]:
  """LAX-backend implementation of `scipy.signal._spectral_helper`.

  Unlike the original helper function, `y` can be None for explicitly
  indicating auto-spectral (non cross-spectral) computation.  In addition to
  this, `detrend` argument is renamed to `detrend_type` for avoiding internal
  name overlap.
  """
  if mode not in ('psd', 'stft'):
    raise ValueError(f"Unknown value for mode {mode}, "
                     "must be one of: ('psd', 'stft')")

  def make_pad(mode, **kwargs):
    def pad(x, n, axis=-1):
      pad_width = [(0, 0) for unused_n in range(x.ndim)]
      pad_width[axis] = (n, n)
      return jnp.pad(x, pad_width, mode, **kwargs)
    return pad

  boundary_funcs = {
      'even': make_pad('reflect'),
      'odd': odd_ext,
      'constant': make_pad('edge'),
      'zeros': make_pad('constant', constant_values=0.0),
      None: lambda x, *args, **kwargs: x
  }

  # Check/ normalize inputs

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Use the public jax.scipy.signal.stft / csd / welch APIs instead of internals
2. If you must call the helper, pass mode='psd' or mode='stft' exactly

assert mode in ('psd', 'stft')  # internal helper only

When it happens

Trigger: Calling the private _spectral_helper with any mode other than 'psd' or 'stft'. Not reachable through public stft/csd APIs.

Common situations: Code that copied jax internals or monkeypatched spectral helpers; very old JAX versions where the helper signature differed.

Related errors

• two-argument mode is available only when mode=='psd'
• Unrecognized {mode=}
• Accumulator aval mismatch: expected {aval}, got {acc.aval}
• {name} cannot accept args with unreduced_kind={mat.unreduced
• Cannot determine the ``__name__`` of the caller.

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