{"record":{"id":"045c12116ec4787e","repo":"vllm-project/vllm","slug":"the-environment-variable-mooncake-config-path-is","errorCode":null,"errorMessage":"The environment variable 'MOONCAKE_CONFIG_PATH' is not set.","messagePattern":"The environment variable 'MOONCAKE_CONFIG_PATH' is not set\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py","lineNumber":174,"sourceCode":"            master_server_address=config.get(\"master_server_address\", \"\"),\n            protocol=config.get(\"protocol\", \"rdma\"),\n            device_name=config.get(\"device_name\", \"\"),\n            mode=config.get(\"mode\", \"embedded\"),\n            global_segment_size=_parse_size(\n                config.get(\"global_segment_size\", DEFAULT_GLOBAL_SEGMENT_SIZE)\n            ),\n            local_buffer_size=_parse_size(\n                config.get(\"local_buffer_size\", DEFAULT_LOCAL_BUFFER_SIZE)\n            ),\n            enable_offload=bool(config.get(\"enable_offload\", False)),\n            tenant_id=_normalize_tenant_id(config.get(\"tenant_id\", DEFAULT_TENANT_ID)),\n        )\n\n    @staticmethod\n    def load_from_config() -> \"MooncakeStoreConfig\":\n        config_path = os.getenv(\"MOONCAKE_CONFIG_PATH\")\n        if not config_path:\n            raise ValueError(\n                \"The environment variable 'MOONCAKE_CONFIG_PATH' is not set.\"\n            )\n        return MooncakeStoreConfig.from_file(config_path)\n\n\ndef _normalize_tenant_id(value: Any) -> str:\n    if value is None:\n        return DEFAULT_TENANT_ID\n    if not isinstance(value, str):\n        raise TypeError(\n            f\"tenant_id must be a string or null, got {type(value).__name__}: {value!r}\"\n        )\n    tenant_id = value.strip()\n    return tenant_id if tenant_id else DEFAULT_TENANT_ID\n\n\ndef _parse_size(value: Any) -> int:\n    \"\"\"Parse storage size strings with units: GB, MB, KB, B.\"\"\"","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py#L156-L192","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Export MOONCAKE_CONFIG_PATH=/path/to/mooncake.json in every worker's environment (all nodes and all DP/TP ranks)","For k8s, add the variable (and the config file via ConfigMap/volume) to the container env of the vLLM pod","Verify with: python -c \\\"import os; print(os.getenv('MOONCAKE_CONFIG_PATH'))\\\" inside the same env the worker runs in"],"exampleFix":"# before\npython -m vllm.entrypoints.openai.api_server \\\n  --kv-transfer-config '{\"kv_connector\":\"MooncakeStoreConnector\",...}'\n\n# after\nexport MOONCAKE_CONFIG_PATH=/etc/mooncake/mooncake.json\npython -m vllm.entrypoints.openai.api_server \\\n  --kv-transfer-config '{\"kv_connector\":\"MooncakeStoreConnector\",...}'","handlingStrategy":"validation","validationCode":"import os\nassert os.environ.get(\"MOONCAKE_CONFIG_PATH\"), \\\n    \"MOONCAKE_CONFIG_PATH must point to mooncake.json\"\nassert os.path.exists(os.environ[\"MOONCAKE_CONFIG_PATH\"])","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set MOONCAKE_CONFIG_PATH in the pod/container spec, not just the launcher shell","Include the env check in deployment health probes/scripts","Mount the config file via ConfigMap/volume alongside the env var"],"tags":["mooncake","environment","config","startup"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}