{"record":{"id":"c3bb612f19fc7e3d","repo":"vllm-project/vllm","slug":"allocation-failed-str-e","errorCode":null,"errorMessage":"Allocation failed: {str(e)}","messagePattern":"Allocation failed: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py","lineNumber":315,"sourceCode":"        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)\n\n            # Convert results to response format\n            response = {\"rank\": rank, \"results\": list(results.items())}\n            return self._json_response(response)\n        except Exception as e:\n            raise HTTPException(\n                status_code=500, detail=f\"Allocation failed: {str(e)}\"\n            ) from e\n\n    async def confirm_write_for_keys(self, request: Request):\n        \"\"\"Confirm write operations for keys.\"\"\"\n        data = await self._read_json(request)\n        rank = data.get(\"rank\")\n        confirmations = data.get(\"confirmations\", [])\n        pages_to_release = data.get(\"pages_to_release\", [])\n\n        # Validate input format\n        if rank is None or not isinstance(confirmations, list):\n            raise HTTPException(\n                status_code=400,\n                detail=\"Invalid request format: need 'rank' and 'confirmations'\",\n            )\n\n        try:","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py#L297-L333","documentation":"A catch-all around state.allocate_pages_for_keys on the metadata server: any exception during allocation (most commonly 'Rank {rank} not initialized', but also malformed key values or internal state errors) is re-raised as HTTP 500 'Allocation failed: <original message>'. The original exception is chained via 'from e' and appears in the detail string.","triggerScenarios":"POST /allocate for a rank that was never initialized, or any server-side allocation error; the endpoint converts it to a 500 with the underlying message embedded.","commonSituations":"Allocation racing ahead of initialization; metadata server restarted losing rank_metadata; keys with unexpected types breaking allocation internals.","solutions":["Read the detail string — it contains the root cause (e.g. 'Rank 3 not initialized' means: initialize first)","Ensure /initialize for the rank succeeds before allocation requests","Check metadata server logs for the chained traceback if the detail is unclear"],"exampleFix":"# before\nresp = requests.post(url, json={'rank': 3, 'keys': keys})  # 500 Allocation failed: Rank 3 not initialized\n\n# after\nrequests.post(url + '/initialize', json={'rank': 3, 'role': 'worker', 'num_pages': 1024})\nresp = requests.post(url, json={'rank': 3, 'keys': keys})\nresp.raise_for_status()","handlingStrategy":"retry","validationCode":"if rank not in state.rank_metadata:\n    requests.post(f'{server}/initialize',\n                  json={'rank': rank, 'role': 'worker', 'num_pages': n_pages})","typeGuard":null,"tryCatchPattern":"resp = requests.post(f'{server}/allocate', json={'rank': rank, 'keys': keys})\nif resp.status_code == 500 and 'not initialized' in resp.text:\n    requests.post(f'{server}/initialize',\n                  json={'rank': rank, 'role': 'worker', 'num_pages': n_pages})\n    resp = requests.post(f'{server}/allocate', json={'rank': rank, 'keys': keys})\nresp.raise_for_status()","preventionTips":["Parse the 500 detail string — it carries the root cause","Initialize ranks idempotently at worker startup to avoid the common cause","Monitor metadata server logs for chained tracebacks"],"tags":["kv-transfer","hf3fs","metadata-server","http-500","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}