sgl-project/sglang · error · ValueError

--bcg-text-buckets must contain at least one positive intege

Error message

--bcg-text-buckets must contain at least one positive integer.

What it means

When bcg_text_buckets is provided (not None), at least one bucket value must be a positive integer; a list of all zero/non-positive values fails _validate_breakable_cuda_graph.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:638

        # BCG graphs are captured per resolution and only replay for that exact
        # latent shape, so the user must declare the resolutions up front. We
        # capture every one of them at warmup; serving then never re-captures.
        if not self.warmup_resolutions:
            # No explicit resolutions: capture the model's default warmup
            # resolution (derived by build_warmup_reqs) so
            # --enable-breakable-cuda-graph works standalone. BCG graphs are
            # resolution-specific; a request at any other resolution simply
            # falls back to eager (the runner never re-captures at serving
            # time). Pass --warmup-resolutions to capture additional shapes.
            logger.info(
                "[Diffusion BCG] --warmup-resolutions unset; capturing the "
                "model default warmup resolution. Requests at other "
                "resolutions run eager."
            )
        if self.bcg_text_buckets is not None and not any(
            int(b) > 0 for b in self.bcg_text_buckets
        ):
            raise ValueError(
                "--bcg-text-buckets must contain at least one positive integer."
            )

    def _adjust_breakable_cuda_graph_support(self):
        if not self.enable_breakable_cuda_graph:
            return

        pipeline_config = getattr(self, "pipeline_config", None)
        pipeline_config_name = type(pipeline_config).__name__
        if (
            pipeline_config_name in BREAKABLE_CUDA_GRAPH_SUPPORTED_PIPELINE_CONFIGS
            and self._is_breakable_cuda_graph_supported_model()
        ):
            if not self.warmup_resolutions:
                self._default_bcg_warmup_resolution()
            return

        logger.warning(

View on GitHub (pinned to 0132848349)

Solutions

1. Include at least one positive integer in --bcg-text-buckets, e.g. [8192]
2. If you don't need custom buckets, pass None/omit the option

Example fix

# before
ServerArgs(..., bcg_text_buckets=[0])
# after
ServerArgs(..., bcg_text_buckets=[4096, 8192])

buckets = cfg.get('bcg_text_buckets')
if buckets is not None and not any(int(b) > 0 for b in buckets):
    raise SystemExit('--bcg-text-buckets needs at least one positive integer')

def valid_text_buckets(b) -> bool:
    return b is None or any(isinstance(x, int) and x > 0 for x in b)

When it happens

Trigger: ServerArgs(bcg_text_buckets=[0, -1]) or a parsed bucket list that contains no value > 0 (e.g. env parsing produced zeros).

Common situations: Misconfigured CUDA graph text bucket list; copying a bucket spec where placeholder 0s were not replaced; sign errors when computing buckets programmatically.

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

• capacity must be positive, got {capacity}
• min_hits must be positive, got {min_hits}
• max_seqlen must be positive, got {max_seqlen}
• --cuda-graph-config[{phase}].backend={backend!r} not allowed
• bad compress_ratio {compress_ratio}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/980e5acc434cdc1b. Report an issue: GitHub.