encode/httpx · error · TypeError

Invalid "auth" argument: {auth!r}

Error message

Invalid "auth" argument: {auth!r}

What it means

Raised as TypeError by BaseClient._build_auth when the 'auth' argument is not None, not a (username, password) tuple, not an httpx.Auth instance, and not callable. httpx supports exactly those four shapes and rejects anything else.

Source

Thrown at httpx/_client.py:455

        Merge a queryparams argument together with any queryparams on the client,
        to create the queryparams used for the outgoing request.
        """
        if params or self.params:
            merged_queryparams = QueryParams(self.params)
            return merged_queryparams.merge(params)
        return params

    def _build_auth(self, auth: AuthTypes | None) -> Auth | None:
        if auth is None:
            return None
        elif isinstance(auth, tuple):
            return BasicAuth(username=auth[0], password=auth[1])
        elif isinstance(auth, Auth):
            return auth
        elif callable(auth):
            return FunctionAuth(func=auth)
        else:
            raise TypeError(f'Invalid "auth" argument: {auth!r}')

    def _build_request_auth(
        self,
        request: Request,
        auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,
    ) -> Auth:
        auth = (
            self._auth if isinstance(auth, UseClientDefault) else self._build_auth(auth)
        )

        if auth is not None:
            return auth

        username, password = request.url.username, request.url.password
        if username or password:
            return BasicAuth(username=username, password=password)

        return Auth()

View on GitHub (pinned to b5addb64f0)

Solutions

1. Pass a 2-tuple: auth=("user", "password").
2. Or pass an httpx.BasicAuth(...) / httpx.DigestAuth(...) instance.
3. Or pass a callable taking a Request and returning a Request.

Example fix

// before
client.get(url, auth="alice:s3cret")
// after
client.get(url, auth=("alice", "s3cret"))

import httpx
from typing import Any

def is_valid_auth(auth: Any) -> bool:
    return (
        auth is None
        or isinstance(auth, tuple)
        or isinstance(auth, httpx.Auth)
        or callable(auth)
    )

# before the request
assert is_valid_auth(auth), f"auth must be None|tuple|httpx.Auth|callable, got {type(auth)!r}"
client.get(url, auth=auth)

from typing import Any
import httpx

def is_valid_auth(auth: Any) -> bool:
    return (
        auth is None
        or isinstance(auth, tuple)
        or isinstance(auth, httpx.Auth)
        or callable(auth)
    )

try:
    client.get(url, auth=auth)
except TypeError as exc:
    raise ValueError(f"Invalid auth credential format: {auth!r}") from exc

When it happens

Trigger: Passing an unsupported value to auth=, e.g. client.get(url, auth="user:pass"), auth={"user":"x"}, auth=["u","p","extra"], or auth=123.

Common situations: Passing credentials as a 'user:password' string instead of a tuple; passing a dict; passing a list of more than two elements; mis-typed config variables.

Related errors

• Malformed Digest WWW-Authenticate header
• Digest auth-int support is not yet implemented
• Unexpected qop value "{qop!r}" in digest auth
• Using http2=True, but the 'h2' package is not installed. Mak
• httpx.Timeout must either include a default, or set all four

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/f03bf25884eac75d.json. Report an issue: GitHub.