sgl-project/sglang · error · ValueError

backend must be a non-empty string

Error message

backend must be a non-empty string

What it means

Raised by register_sampler_backend() when the backend name passed in is empty (empty string or None). SGLang requires every custom sampler backend to be identified by a non-empty string key that gets added to SAMPLING_BACKend_CHOICES, so an empty key is rejected up front.

Source

Thrown at python/sglang/srt/layers/sampler.py:535

        sampling_info: SamplingBatchInfo,
        top_logprobs_nums: List[int],
        token_ids_logprobs: List[List[int]],
    ) -> None:
        logprob_result = self.output_logprob_processor.compute_logprobs_only(
            next_token_logits=logits_output.next_token_logits,
            top_logprobs_nums=top_logprobs_nums,
            token_ids_logprobs=token_ids_logprobs,
            preprocess_fn=partial(self._preprocess_logits, sampling_info=sampling_info),
        )
        if logprob_result is not None:
            logprob_result.write_output_to(logits_output)


def register_sampler_backend(backend: str, factory: Callable[[], "Sampler"]) -> None:
    """Register a custom sampler factory for a backend string."""

    if not backend:
        raise ValueError("backend must be a non-empty string")

    from sglang.srt.server_args import SAMPLING_BACKEND_CHOICES

    if backend in _CUSTOM_SAMPLER_FACTORIES:
        logger.warning("Overriding existing sampler factory for backend '%s'", backend)
    SAMPLING_BACKEND_CHOICES.add(backend)
    _CUSTOM_SAMPLER_FACTORIES[backend] = factory


def create_sampler(backend: Optional[str] = None) -> "Sampler":
    """Create a sampler honoring custom backend registrations."""

    server_args = get_server_args()
    backend = backend or (get_exec().kernel.sampling_backend if server_args else None)

    if backend in _CUSTOM_SAMPLER_FACTORIES:
        sampler = _CUSTOM_SAMPLER_FACTORIES[backend]()
        if not isinstance(sampler, Sampler):

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a non-empty, unique string as the backend name, e.g. 'oracle' or 'custom_info'
2. If the name comes from config, validate/default it before registering: backend = backend or 'my_backend'
3. Pick a name that does not collide with built-ins unless you intend the logged override warning

Example fix

// before
register_sampler_backend('', my_factory)
// after
register_sampler_backend('my_custom_sampler', my_factory)

from sglang.srt.layers.sampler import register_sampler_backend

name = name.strip() if isinstance(name, str) else ''
if not name:
    raise ValueError('sampler backend name must be a non-empty string')
register_sampler_backend(name, factory)

When it happens

Trigger: Calling register_sampler_backend('', factory) or register_sampler_backend(None, factory). Callers like install_oracle_sampler / install_customized_info_sampler pass a hard-coded name, so this is only hit by user code registering its own backend with a bad name variable.

Common situations: Programmatically deriving the backend name from a config value or model name that turns out to be empty; copy-pasting a registration snippet and forgetting to fill in the name.

Related errors

• v_cache must be provided
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True
• Invalid arch format: {arch_str}
• KernelSpec.target must be 'module:attr', got {self.target!r}

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