sgl-project/sglang · error · ValueError

{env_field.name}={template!r} must contain '{{global_rank}}'

Error message

{env_field.name}={template!r} must contain '{{global_rank}}': each rank needs its own path, and a rank-independent one would point every rank at a single daemon.

What it means

_format_daemon_path requires the socket/ready path template (env var) to contain '{global_rank}'. A rank-independent path would point all TP ranks at one daemon and they would map the wrong shard, so it refuses up front.

Source

Thrown at python/sglang/srt/weight_cache/protocol.py:315

    """
    return (
        base_gpu_id
        + (pp_rank % pp_size_per_node) * tp_size_per_node
        + (tp_rank % tp_size_per_node) * gpu_id_step
    )


def _format_daemon_path(env_field, global_rank: int) -> str:
    """Fill in a daemon path template, rejecting one that drops the rank.

    The template is user-overridable, and ``str.format`` silently ignores a
    missing placeholder. Every rank would then derive the same path and map the
    shard belonging to whichever daemon got there first, so refuse up front
    rather than serve wrong weights.
    """
    template = env_field.get()
    if "{global_rank}" not in template:
        raise ValueError(
            f"{env_field.name}={template!r} must contain '{{global_rank}}': each "
            f"rank needs its own path, and a rank-independent one would point "
            f"every rank at a single daemon."
        )
    return template.format(global_rank=global_rank)


def get_socket_path(global_rank: int) -> str:
    """Get the Unix socket path for a weight cache daemon.

    global_rank = tp_size * pp_rank + tp_rank
    """
    return _format_daemon_path(envs.SGLANG_WEIGHT_CACHE_SOCKET_TEMPLATE, global_rank)


def get_ready_path(global_rank: int) -> str:
    """Get the ready-file path for a weight cache daemon.

View on GitHub (pinned to 0132848349)

Solutions

1. Add {global_rank} to the template, e.g. /tmp/wcache-rank{global_rank}.sock
2. Use the default template by unsetting the env var

Example fix

# before
export SGLANG_WEIGHT_CACHE_SOCKET_PATH=/tmp/wcache.sock
# after
export SGLANG_WEIGHT_CACHE_SOCKET_PATH=/tmp/wcache-rank{global_rank}.sock

if '{global_rank}' not in template:
    raise ValueError('add {global_rank} to path template')

When it happens

Trigger: Setting SGLANG_WEIGHT_CACHE_*_PATH (socket or ready template) without the {global_rank} placeholder; called from get_socket_path/get_ready_path.

Common situations: User overrides the default per-rank path template with a fixed path like /tmp/wcache.sock when running tensor parallel > 1.

Related errors

• Cosmos3CausalAttention requires num_attention_heads divisibl
• TP size must be positive.
• MiniMax H3 {name}={value} must be divisible by TP size {tp_s
• Config file path not set. Please set {envs.SGLANG_HICACHE_MO
• [weight_cache:{where}] quantization method {quant_method!r}

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