vllm-project/vllm · error · ValueError

The environment variable 'MOONCAKE_CONFIG_PATH' is not set.

Error message

The environment variable 'MOONCAKE_CONFIG_PATH' is not set.

What it means

MooncakeStoreConfig.load_from_config() locates the worker-side mooncake config exclusively via the MOONCAKE_CONFIG_PATH environment variable; if it is unset or empty, the worker cannot build its store config and raises ValueError at startup.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py:174

            master_server_address=config.get("master_server_address", ""),
            protocol=config.get("protocol", "rdma"),
            device_name=config.get("device_name", ""),
            mode=config.get("mode", "embedded"),
            global_segment_size=_parse_size(
                config.get("global_segment_size", DEFAULT_GLOBAL_SEGMENT_SIZE)
            ),
            local_buffer_size=_parse_size(
                config.get("local_buffer_size", DEFAULT_LOCAL_BUFFER_SIZE)
            ),
            enable_offload=bool(config.get("enable_offload", False)),
            tenant_id=_normalize_tenant_id(config.get("tenant_id", DEFAULT_TENANT_ID)),
        )

    @staticmethod
    def load_from_config() -> "MooncakeStoreConfig":
        config_path = os.getenv("MOONCAKE_CONFIG_PATH")
        if not config_path:
            raise ValueError(
                "The environment variable 'MOONCAKE_CONFIG_PATH' is not set."
            )
        return MooncakeStoreConfig.from_file(config_path)


def _normalize_tenant_id(value: Any) -> str:
    if value is None:
        return DEFAULT_TENANT_ID
    if not isinstance(value, str):
        raise TypeError(
            f"tenant_id must be a string or null, got {type(value).__name__}: {value!r}"
        )
    tenant_id = value.strip()
    return tenant_id if tenant_id else DEFAULT_TENANT_ID


def _parse_size(value: Any) -> int:
    """Parse storage size strings with units: GB, MB, KB, B."""

View on GitHub (pinned to c794754062)

Solutions

1. Export MOONCAKE_CONFIG_PATH=/path/to/mooncake.json in every worker's environment (all nodes and all DP/TP ranks)
2. For k8s, add the variable (and the config file via ConfigMap/volume) to the container env of the vLLM pod
3. Verify with: python -c \"import os; print(os.getenv('MOONCAKE_CONFIG_PATH'))\" inside the same env the worker runs in

Example fix

# before
python -m vllm.entrypoints.openai.api_server \
  --kv-transfer-config '{"kv_connector":"MooncakeStoreConnector",...}'

# after
export MOONCAKE_CONFIG_PATH=/etc/mooncake/mooncake.json
python -m vllm.entrypoints.openai.api_server \
  --kv-transfer-config '{"kv_connector":"MooncakeStoreConnector",...}'

import os
assert os.environ.get("MOONCAKE_CONFIG_PATH"), \
    "MOONCAKE_CONFIG_PATH must point to mooncake.json"
assert os.path.exists(os.environ["MOONCAKE_CONFIG_PATH"])

When it happens

Trigger: Starting vLLM with the MooncakeStoreConnector (or any code path calling load_from_config) without exporting MOONCAKE_CONFIG_PATH, or exporting it only in one of DP/TP worker processes (e.g. set in the launcher shell but not in a container/k8s env).

Common situations: Kubernetes pods where the env var is missing from the container spec; multi-node launches where one node forgets the export; CI shells that strip the environment.

Related errors

• cannot use in-process coordinator with bootstrapped transpor
• failed to parse `RUST_LOG`
• The quantization method %s is deprecated and will be removed
• Number of experts in the model must be greater than 0 when e
• Total number of attention heads ({total_num_attention_heads}

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/045c12116ec4787e. Report an issue: GitHub.