xai-org/x-algorithm · error · ValueError

beam_width must be >= 1, got {self.beam_width}. Use --beam_w

Error message

beam_width must be >= 1, got {self.beam_width}. Use --beam_width=N on the launch command.

What it means

Raised by _setup_sid_retrieval_jit during SID (semantic ID) retrieval setup, which runs as part of checkpoint loading (maybe_load_checkpoint). The runner validates that beam_width, the beam-search width for the RIPS/SID retrieval index, is at least 1 before building the JIT-compiled retrieval pipeline. A value of 0 or negative would make beam search degenerate, so it fails fast with an actionable message pointing at the launch flag.

Source

Thrown at phoenix/xrex/inference/sid_retrieval_runner.py:76

@configclass
class SidRetrievalModelRunner(
    BaseModelRunner[
        xai_recsys_engine.RetrieveRequestBatch,
        RecsysSIDRetrievalConfig,
    ]
):
    sid_retrieval_forward_jit: JittedOrCompiled | None = None
    sid_retrieval_forward_fn: hk.Transformed | None = None
    beam_width: int = 1
    decode_levels: int = 0

    _corpus: _CorpusView | None = None

    def _setup_sid_retrieval_jit(self) -> None:
        assert isinstance(self.model_config, RecsysSIDRetrievalConfig)
        if self.beam_width < 1:
            raise ValueError(
                f"beam_width must be >= 1, got {self.beam_width}. "
                "Use --beam_width=N on the launch command."
            )
        logger.info(
            "Setting up SID retrieval JIT: beam_width=%d "
            "sid_num_levels=%d sid_codebook_size=%d corpus_size=%d large_k=%d",
            self.beam_width,
            self.model_config.sid_num_levels,
            self.model_config.sid_codebook_size,
            self._corpus.num_posts if self._corpus is not None else 0,
            self.large_k,
        )

        _ht = self.model_config.hash_table.hash_keys
        _hist_post_seq = _ht.num_item_hashes * self.history_seq_len
        _hist_auth_seq = _ht.num_author_hashes * self.history_seq_len
        _cand_post_seq = _ht.num_item_hashes * self.candidate_seq_len
        _cand_auth_seq = _ht.num_author_hashes * self.candidate_seq_len

View on GitHub (pinned to 24c60942c5)

Solutions

1. Set --beam_width=1 (greedy) or higher on the launch command.
2. Check the runner/config constructor for a beam_width field defaulting to 0 and override it.
3. If beam_width comes from a sweep or generated config, clamp it with max(1, beam_width) before launch.

Example fix

# before
--beam_width=0

# after
--beam_width=4

beam_width = int(os.environ.get("BEAM_WIDTH", 1))
assert beam_width >= 1, f"beam_width must be >= 1, got {beam_width}"

def is_valid_beam_width(bw) -> bool:
    return isinstance(bw, int) and not isinstance(bw, bool) and bw >= 1

When it happens

Trigger: Launching inference/training with --beam_width=0 (or a negative value) on the launch command, or constructing the runner with a beam_width defaulting to 0 via config, when maybe_load_checkpoint triggers _setup_sid_retrieval_jit.

Common situations: Copy-pasted launch commands where beam_width was set to 0 to 'disable' beam search; config files with beam_width: 0 meaning 'use default'; a sweep script enumerating beam widths starting at 0.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• beam_width must be >= 1, got {beam_width}
• sink policy {resolved}: unknown keys {sorted(unknown)}
• `clusters` must contain at least one region
• Region {region!r} must list at least one broker
• `clusters` must contain at least one region

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/cee4aad19831ea20. Report an issue: GitHub.