jax-ml/jax · error · ValueError

noverlap must be less than nperseg.

Error message

noverlap must be less than nperseg.

What it means

Segments overlap by noverlap samples, requiring at least one new sample per step (nstep = nperseg - noverlap > 0). noverlap >= nperseg would make step size zero or negative, producing no progress, so it is rejected.

Source

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

  x = jnp.moveaxis(x, axis, -1)
  if y is not None and y_arr.ndim > 1:
    y_arr = jnp.moveaxis(y_arr, axis, -1)

  # Check if x and y are the same length, zero-pad if necessary
  if y is not None and x.shape[-1] != y_arr.shape[-1]:
    if x.shape[-1] < y_arr.shape[-1]:
      pad_shape = list(x.shape)
      pad_shape[-1] = y_arr.shape[-1] - x.shape[-1]
      x = jnp.concatenate((x, jnp.zeros_like(x, shape=pad_shape)), -1)
    else:
      pad_shape = list(y_arr.shape)
      pad_shape[-1] = x.shape[-1] - y_arr.shape[-1]
      y_arr = jnp.concatenate((y_arr, jnp.zeros_like(x, shape=pad_shape)), -1)

  if nfft_int < nperseg_int:
    raise ValueError('nfft must be greater than or equal to nperseg.')
  if noverlap_int >= nperseg_int:
    raise ValueError('noverlap must be less than nperseg.')
  nstep = nperseg_int - noverlap_int

  # Apply paddings
  if boundary is not None:
    ext_func = boundary_funcs[boundary]
    x = ext_func(x, nperseg_int // 2, axis=-1)
    if y is not None:
      y_arr = ext_func(y_arr, nperseg_int // 2, axis=-1)

  if padded:
    # Pad to integer number of windowed segments
    # I.e make x.shape[-1] = nperseg + (nseg-1)*nstep, with integer nseg
    nadd = (-(x.shape[-1]-nperseg_int) % nstep) % nperseg_int
    x = jnp.concatenate((x, jnp.zeros_like(x, shape=(*x.shape[:-1], nadd))), axis=-1)
    if y is not None:
      y_arr = jnp.concatenate((y_arr, jnp.zeros_like(x, shape=(*y_arr.shape[:-1], nadd))), axis=-1)

  # Handle detrending and window functions

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Reduce noverlap to at most nperseg - 1 (typically int(nperseg * 0.75))
2. If noverlap is derived, clamp: noverlap = min(nperseg - 1, noverlap)
3. When wanting maximal overlap with hop 1, set noverlap = nperseg - 1

Example fix

// before
jax.scipy.signal.stft(x, nperseg=256, noverlap=256)
// after
jax.scipy.signal.stft(x, nperseg=256, noverlap=255)

noverlap = min(int(noverlap), int(nperseg) - 1) if noverlap is not None else None

When it happens

Trigger: stft(x, nperseg=256, noverlap=256); using noverlap = nperseg for 'maximum overlap'; scipy-style defaults copied onto a smaller nperseg.

Common situations: High-overlap analysis settings where overlap ratio is rounded up to the full segment length; parameter sweeps that hit the boundary.

Related errors

• nperseg must be a positive integer
• nfft must be greater than or equal to nperseg.
• ind must be a positive integer; got {ind=}
• Expected kind to be on of: {valid_kind}; got {kind}
• Expected kind to be one of: {valid_kind}; got {kind}

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