What causes "Invalid initialization parameters" in vllm-project/vllm?

Send role='scheduler' for scheduler processes (no num_pages needed)

vllm-project/vllm · error · HTTPException

Invalid initialization parameters

Error message

Invalid initialization parameters

What it means

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'.

Source

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

    async def initialize_rank(self, rank: int, request: Request):
        """Initialize a rank with specified number of pages."""
        data = await self._read_json(request)
        role = data.get("role", "worker")
        num_pages = data.get("num_pages", 0)

        if role == "scheduler":
            return self._json_response(
                {"message": "Scheduler role does not require initialization"}
            )

        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)

View on GitHub (pinned to c794754062)

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)

Example fix

# before
requests.post(url + '/initialize', json={'rank': 0, 'role': 'Worker', 'num_pages': 0})

# after
requests.post(url + '/initialize', json={'rank': 0, 'role': 'worker', 'num_pages': 1024})

Defensive patterns

Strategy: validation

Validate before calling

assert role in ('scheduler', 'worker')
assert role == 'scheduler' or num_pages > 0
requests.post(f'{server}/initialize',
              json={'rank': rank, 'role': role, 'num_pages': num_pages})

Try / catch

resp = requests.post(f'{server}/initialize', json=payload)
if resp.status_code == 400:
    raise SystemExit(f'Bad init payload {payload}: {resp.text}')

Prevention

Use the provided client helpers instead of hand-rolled HTTP calls
Validate role/num_pages pairs in config before deployment

When it happens

Trigger: POSTing to the init endpoint with role missing/misspelled (not 'scheduler'/'worker'), or role='worker' together with num_pages=0 or negative.

Common situations: 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.

Related errors

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