vllm-project/vllm · error · HTTPException

Invalid request format: need 'rank' and 'keys'

Error message

Invalid request format: need 'rank' and 'keys'

What it means

The batch page-allocation endpoint requires a JSON body containing 'rank' (non-null) and 'keys' (a list). Missing rank, or keys that is not a list (e.g. a string or dict), yields HTTP 400 with this message.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_metadata_server.py:303

        if role == "worker" and num_pages > 0:
            self.state.initialize_rank(rank, num_pages)
            return self._json_response(
                {"message": f"Rank {rank} initialized with {num_pages} pages"}
            )
        else:
            raise HTTPException(
                status_code=400, detail="Invalid initialization parameters"
            )

    async def batch_allocate_pages_for_keys(self, request: Request):
        """Allocate one page for each key on a specific rank."""
        data = await self._read_json(request)
        rank = data.get("rank")
        keys = data.get("keys", [])

        # Validate input format
        if rank is None or not isinstance(keys, list):
            raise HTTPException(
                status_code=400, detail="Invalid request format: need 'rank' and 'keys'"
            )

        try:
            # Perform allocation
            results = self.state.allocate_pages_for_keys(rank, keys)

            # Convert results to response format
            response = {"rank": rank, "results": list(results.items())}
            return self._json_response(response)
        except Exception as e:
            raise HTTPException(
                status_code=500, detail=f"Allocation failed: {str(e)}"
            ) from e

    async def confirm_write_for_keys(self, request: Request):
        """Confirm write operations for keys."""
        data = await self._read_json(request)

View on GitHub (pinned to c794754062)

Solutions

  1. Include both fields: {'rank': <int>, 'keys': [<str>, ...]}
  2. Client-side validate before the request: rank is not None and isinstance(keys, list)
  3. Log the exact request body on 400 to catch serialization bugs

Example fix

# before
requests.post(url, json={'keys': 'blk1,blk2'})  # rank missing, keys is str

# after
requests.post(url, json={'rank': 1, 'keys': ['blk1', 'blk2']})
Defensive patterns

Strategy: validation

Validate before calling

assert rank is not None and isinstance(keys, list)
requests.post(f'{server}/allocate', json={'rank': rank, 'keys': keys})

Type guard

def valid_alloc_payload(payload: dict) -> bool:
    return payload.get('rank') is not None and isinstance(payload.get('keys'), list)

Try / catch

resp = requests.post(url, json=payload)
if resp.status_code == 400 and 'rank' in resp.text:
    raise SystemExit(f'Malformed allocate request: {payload}')

Prevention

When it happens

Trigger: POSTing to the allocation endpoint with rank omitted/null, or keys absent / passed as a non-list JSON value.

Common situations: Client sends an empty keys value of the wrong type, serializes keys as a comma-separated string, or the JSON body is malformed so .get() returns defaults.

Related errors

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