{"id":"cdc0614f164b3c00","repo":"encode/httpx","slug":"key-r-is-an-invalid-keyword-argument-for-url","errorCode":null,"errorMessage":"{key!r} is an invalid keyword argument for URL()","messagePattern":"(.+?) is an invalid keyword argument for URL\\(\\)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"httpx/_urls.py","lineNumber":98,"sourceCode":"                \"scheme\": str,\n                \"username\": str,\n                \"password\": str,\n                \"userinfo\": bytes,\n                \"host\": str,\n                \"port\": int,\n                \"netloc\": bytes,\n                \"path\": str,\n                \"query\": bytes,\n                \"raw_path\": bytes,\n                \"fragment\": str,\n                \"params\": object,\n            }\n\n            # Perform type checking for all supported keyword arguments.\n            for key, value in kwargs.items():\n                if key not in allowed:\n                    message = f\"{key!r} is an invalid keyword argument for URL()\"\n                    raise TypeError(message)\n                if value is not None and not isinstance(value, allowed[key]):\n                    expected = allowed[key].__name__\n                    seen = type(value).__name__\n                    message = f\"Argument {key!r} must be {expected} but got {seen}\"\n                    raise TypeError(message)\n                if isinstance(value, bytes):\n                    kwargs[key] = value.decode(\"ascii\")\n\n            if \"params\" in kwargs:\n                # Replace any \"params\" keyword with the raw \"query\" instead.\n                #\n                # Ensure that empty params use `kwargs[\"query\"] = None` rather\n                # than `kwargs[\"query\"] = \"\"`, so that generated URLs do not\n                # include an empty trailing \"?\".\n                params = kwargs.pop(\"params\")\n                kwargs[\"query\"] = None if not params else str(QueryParams(params))\n\n        if isinstance(url, str):","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/encode/httpx/blob/b5addb64f0161ff6bfe94c124ef76f6a1fba5254/httpx/_urls.py#L80-L116","documentation":"Raised by URL.__init__ when a keyword argument name is not in the allowed set {scheme, username, password, userinfo, host, port, netloc, path, query, raw_path, fragment, params}. This is a strict constructor: any other kwarg is a programmer error and rejected as TypeError before any parsing.","triggerScenarios":"httpx.URL('https://x', timeout=10), httpx.URL(method='GET'), httpx.URL(headers=...), or any typo like httpx.URL('https://x', passwrod='x').","commonSituations":"Confusing URL constructor kwargs with Client kwargs (timeout, headers, auth); spelling mistakes; passing through an unvalidated dict as **kwargs.","solutions":["Check the allowed keys list and remove unsupported kwargs before construction.","Pass request-level options (timeout, headers) to client.request()/client.get(), not to URL().","Filter kwargs through an allowlist when spreading a dynamic dict.","Use an IDE/linter to catch unknown kwargs at authoring time."],"exampleFix":"// before\nurl = httpx.URL(\"https://example.com\", timeout=5.0)  # TypeError: invalid keyword\n\n// after\nurl = httpx.URL(\"https://example.com\")\nclient.get(url, timeout=5.0)","handlingStrategy":"type-guard","validationCode":"ALLOWED_URL_KWARGS = {\n    \"scheme\", \"username\", \"password\", \"userinfo\", \"host\", \"port\",\n    \"netloc\", \"path\", \"query\", \"raw_path\", \"fragment\", \"params\",\n}\n\ndef filtered_url_kwargs(kwargs: dict) -> dict:\n    bad = set(kwargs) - ALLOWED_URL_KWARGS\n    if bad:\n        raise TypeError(f\"Unsupported URL kwargs: {sorted(bad)}\")\n    return kwargs\n\nurl = httpx.URL(base, **filtered_url_kwargs(user_kwargs))","typeGuard":"def are_valid_url_kwargs(kwargs: dict) -> bool:\n    allowed = {\n        \"scheme\", \"username\", \"password\", \"userinfo\", \"host\", \"port\",\n        \"netloc\", \"path\", \"query\", \"raw_path\", \"fragment\", \"params\",\n    }\n    return set(kwargs).issubset(allowed)","tryCatchPattern":"try:\n    url = httpx.URL(base, **kwargs)\nexcept TypeError as e:\n    if \"invalid keyword argument for URL()\" in str(e):\n        raise TypeError(f\"Bad URL kwarg. Allowed: scheme/username/password/host/...\") from e\n    raise","preventionTips":["Never spread unfiltered dicts into httpx.URL().","Pass request options (timeout/headers/auth) to the request call, not URL().","Use static typing/linters to catch unknown kwargs at authoring time."],"tags":["url","api-misuse","validation","typeerror"],"analyzedSha":"b5addb64f0161ff6bfe94c124ef76f6a1fba5254","analyzedAt":"2026-08-04T19:32:56.768Z","schemaVersion":2}