{"record":{"id":"0dee14fd3a9caf9b","repo":"vllm-project/vllm","slug":"invalid-initialization-parameters","errorCode":null,"errorMessage":"Invalid initialization parameters","messagePattern":"Invalid initialization parameters","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py","lineNumber":291,"sourceCode":"\n    async def initialize_rank(self, rank: int, request: Request):\n        \"\"\"Initialize a rank with specified number of pages.\"\"\"\n        data = await self._read_json(request)\n        role = data.get(\"role\", \"worker\")\n        num_pages = data.get(\"num_pages\", 0)\n\n        if role == \"scheduler\":\n            return self._json_response(\n                {\"message\": \"Scheduler role does not require initialization\"}\n            )\n\n        if role == \"worker\" and num_pages > 0:\n            self.state.initialize_rank(rank, num_pages)\n            return self._json_response(\n                {\"message\": f\"Rank {rank} initialized with {num_pages} pages\"}\n            )\n        else:\n            raise HTTPException(\n                status_code=400, detail=\"Invalid initialization parameters\"\n            )\n\n    async def batch_allocate_pages_for_keys(self, request: Request):\n        \"\"\"Allocate one page for each key on a specific rank.\"\"\"\n        data = await self._read_json(request)\n        rank = data.get(\"rank\")\n        keys = data.get(\"keys\", [])\n\n        # Validate input format\n        if rank is None or not isinstance(keys, list):\n            raise HTTPException(\n                status_code=400, detail=\"Invalid request format: need 'rank' and 'keys'\"\n            )\n\n        try:\n            # Perform allocation\n            results = self.state.allocate_pages_for_keys(rank, keys)","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py#L273-L309","documentation":"The metadata server's /initialize endpoint accepts only two valid combinations: role='scheduler' (no pages needed) or role='worker' with num_pages > 0. Anything else — unknown role, or worker with num_pages <= 0 — gets HTTP 400 'Invalid initialization parameters'.","triggerScenarios":"POSTing to the init endpoint with role missing/misspelled (not 'scheduler'/'worker'), or role='worker' together with num_pages=0 or negative.","commonSituations":"Hand-rolled HTTP clients or curl scripts with typos in 'role'; defaulting num_pages to 0; schema drift between the client helper and the server's expected fields.","solutions":["Send role='scheduler' for scheduler processes (no num_pages needed)","Send role='worker' with a positive integer num_pages sized to the rank's page capacity","Validate the request body before sending: role in {'scheduler','worker'} and (role=='scheduler' or num_pages>0)"],"exampleFix":"# before\nrequests.post(url + '/initialize', json={'rank': 0, 'role': 'Worker', 'num_pages': 0})\n\n# after\nrequests.post(url + '/initialize', json={'rank': 0, 'role': 'worker', 'num_pages': 1024})","handlingStrategy":"validation","validationCode":"assert role in ('scheduler', 'worker')\nassert role == 'scheduler' or num_pages > 0\nrequests.post(f'{server}/initialize',\n              json={'rank': rank, 'role': role, 'num_pages': num_pages})","typeGuard":null,"tryCatchPattern":"resp = requests.post(f'{server}/initialize', json=payload)\nif resp.status_code == 400:\n    raise SystemExit(f'Bad init payload {payload}: {resp.text}')","preventionTips":["Use the provided client helpers instead of hand-rolled HTTP calls","Validate role/num_pages pairs in config before deployment"],"tags":["kv-transfer","hf3fs","metadata-server","http-400","validation","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}