BerriAI/litellm · warning · ManagementProblem

urn:litellm:error:unknown-query-parameter

urn:litellm:error:unknown-query-parameter

Error message

Unrecognized query parameter(s): {', '.join(unknown)}.

What it means

Part of the v1 management API's strict-input contract: reject_unknown_query_params compares every incoming query parameter name against what the route declared and 400s on any extra one. The rationale in code is that a silently ignored filter over-returns data — worse than a rejected request. The response is a problem document (type urn:litellm:error:unknown-query-parameter) naming the unknown parameters and the allowed set.

Source

Thrown at litellm/proxy/management_endpoints/management_v1/common.py:80

        type=f"{PROBLEM_TYPE_BASE}unknown-query-parameter",
        title="Unknown query parameter",
        status=400,
        detail=f"Unrecognized query parameter(s): {', '.join(unknown)}.",
        allowed=sorted(allowed),
    )


async def reject_unknown_query_params(request: Request) -> None:
    """Reject any query param the route did not declare.

    A silently ignored filter over-returns data, which is worse than a rejected
    request; a fresh surface is the only chance to be strict about it.
    """
    declared: Final = _declared_query_params(request)
    unknown: Final[tuple[str, ...]] = tuple(sorted(name for name in request.query_params if name not in declared))
    if not unknown:
        return
    raise ManagementProblem(unknown_query_param_problem(unknown=unknown, allowed=tuple(sorted(declared))))


def _page_url(request: Request, page: int) -> str:
    others: Final = tuple((key, value) for key, value in request.query_params.multi_items() if key != "page")
    return f"{request.url.path}?{urlencode((*others, ('page', page)))}"


def build_page_links(request: Request, page: int, has_more: bool) -> PageLinks:
    return PageLinks(
        self_link=_page_url(request, page),
        prev=_page_url(request, page - 1) if page > 1 else None,
        next=_page_url(request, page + 1) if has_more else None,
    )


def build_list_links(request: Request, page: int, total_pages: int) -> ListLinks:
    """Page-mode links. `last` clamps to page 1 on an empty result set so every link still resolves."""
    last: Final = max(total_pages, 1)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Remove or correct the parameter — the error's 'allowed' list (and the endpoint docstring) enumerates exactly what is accepted
2. Update the client SDK to the matching proxy version so param names line up
3. For filters, use the declared filter[...] bracket syntax rather than inventing top-level names
4. Watch for the sibling 'duplicate-query-parameter' problem: each param may appear only once

Example fix

# before
curl 'http://localhost:4000/management/v1/budgets?pag_size=25'   # 400 unknown-query-parameter
# after
curl 'http://localhost:4000/management/v1/budgets?page_size=25'

ALLOWED = {'page', 'page_size', 'sort', 'search'}  # keep per-route, from the endpoint docs

def clean_query(q: dict) -> dict:
    unknown = set(q) - ALLOWED
    if unknown:
        raise ValueError(f'params not accepted by this route: {sorted(unknown)}; allowed: {sorted(ALLOWED)}')
    return q

try:
    r = await client.get('/management/v1/budgets', params=clean_query(q))
    r.raise_for_status()
except httpx.HTTPStatusError as e:
    if 'unknown-query-parameter' in e.response.text:
        allowed = e.response.json().get('detail', '')   # lists allowed params; adjust q accordingly
        raise ValueError(f'fix query params: {allowed}') from e
    raise

When it happens

Trigger: curl '.../management/v1/budgets?bucket=prod' (no such param); typos like ?pag_size=25, ?sortDirection=desc, or ?organization_id=... on a route that does not declare it; SDK code written against a different (older/newer) route signature.

Common situations: Porting integrations from the legacy /key/list-style endpoints whose params differ; version skew between client SDK and proxy; leftover params appended by shared HTTP helper code.

Related errors

• urn:litellm:error:unknown-query-parameter
• Please provide start_date and end_date
• Invalid sort order. Must be 'asc' or 'desc'
• urn:litellm:error:database-not-connected
• mcp_tools_config must be a list of dictionaries

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/dd0a23e1d013e0ab. Report an issue: GitHub.