{"record":{"id":"377b6a00ac16d29f","repo":"vllm-project/vllm","slug":"invalid-request-format-need-rank-and-confirmat","errorCode":null,"errorMessage":"Invalid request format: need 'rank' and 'confirmations'","messagePattern":"Invalid request format: need 'rank' and 'confirmations'","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py","lineNumber":328,"sourceCode":"\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:\n            self.state.confirm_write_for_keys(rank, confirmations, pages_to_release)\n\n            return Response(status_code=204)\n\n        except Exception as e:\n            logger.error(\"Confirm write for keys failed: %s\", e)\n            raise HTTPException(\n                status_code=500, detail=f\"Confirmation failed: {str(e)}\"\n            ) from e\n\n    async def batch_key_exists(self, request: Request):\n        \"\"\"Check if multiple keys exist in metadata.\"\"\"\n        data = await self._read_json(request)","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py#L310-L346","documentation":"Raised as an HTTP 400 by the HF3FS metadata server's confirm_write_for_keys endpoint when the POST body either omits 'rank' (or it is null) or has a 'confirmations' field that is not a JSON list. It is a request-validation error: the server refuses to process the confirmation because it cannot identify the rank or iterate the confirmations. The client of this API is the HF3FS KV connector worker, so seeing it means the connector sent a malformed payload.","triggerScenarios":"POST to the confirm_write_for_keys route with body {'confirmations': [...] } (rank missing/null), or with 'confirmations' as a string/dict/number instead of a list; also triggered by sending 'pages_to_release' alone without 'rank'.","commonSituations":"Hand-rolled test scripts against the metadata server that forget the rank field; version skew between the metadata server and the connector client where the wire format changed; JSON serialization bugs that wrap confirmations in an object.","solutions":["Ensure the request body contains a non-null integer 'rank' and a list 'confirmations' (empty list is accepted).","Check the connector client version matches the metadata server version so the payload schema agrees.","When testing manually, replay the exact payload shape used by HF3FSMetadataClient (rank, confirmations, pages_to_release)."],"exampleFix":"// before\nawait client.post(\"/confirm_write_for_keys\", json={\"confirmations\": cs})\n// after\nawait client.post(\"/confirm_write_for_keys\", json={\"rank\": rank, \"confirmations\": cs, \"pages_to_release\": []})","handlingStrategy":"validation","validationCode":"def confirm_payload_valid(rank, confirmations):\n    return rank is not None and isinstance(confirmations, list)","typeGuard":null,"tryCatchPattern":"Catch HTTPException/HTTPStatusError client-side; on status 400, log the request body and fix the client payload — retrying unchanged will fail again.","preventionTips":["Always build requests through the HF3FSMetadataClient wrapper methods","Add a JSON schema check in tests for every payload the client sends"],"tags":["hf3fs","metadata-server","http-400","request-validation","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}