psf/requests · warning · NotImplementedError

Cookie headers should be added with add_unredirected_header(

Error message

Cookie headers should be added with add_unredirected_header()

What it means

A NotImplementedError raised by MockRequest.add_header() in src/requests/cookies.py. MockRequest is the shim Requests hands to the stdlib http.cookiejar machinery so it can operate on a Requests PreparedRequest; cookiejar is only ever expected to add the Cookie header via add_unredirected_header(), so add_header() is deliberately unimplemented (per the inline comment: 'cookiejar has no legitimate use for this method; add it back if you find one').

Source

Thrown at src/requests/cookies.py:91

                parsed.path,
                parsed.params,
                parsed.query,
                parsed.fragment,
            ]
        )

    def is_unverifiable(self) -> bool:
        return True

    def has_header(self, name: str) -> bool:
        return name in self._r.headers or name in self._new_headers

    def get_header(self, name: str, default: str | None = None) -> str | None:
        return self._r.headers.get(name, self._new_headers.get(name, default))  # type: ignore[return-value]

    def add_header(self, key: str, val: str) -> None:
        """cookiejar has no legitimate use for this method; add it back if you find one."""
        raise NotImplementedError(
            "Cookie headers should be added with add_unredirected_header()"
        )

    def add_unredirected_header(self, name: str, value: str) -> None:
        self._new_headers[name] = value

    def get_new_headers(self) -> dict[str, str]:
        return self._new_headers

    @property
    def unverifiable(self) -> bool:
        return self.is_unverifiable()

    @property
    def origin_req_host(self) -> str:
        return self.get_origin_req_host()

    @property

View on GitHub ↗ (pinned to 414f0513c3)

Solutions

Change the custom cookiejar/policy code to call add_unredirected_header(name, value) instead of add_header().
If you're setting headers on a request, set them via requests' own API (headers= kwarg or PreparedRequest.headers), not through the cookiejar MockRequest shim.
If porting a legacy urllib CookieJar subclass, restrict it to the stdlib CookieJar interface Requests actually exercises.

Example fix

# before (custom cookie policy)
request.add_header("Cookie", cookie_str)

# after
request.add_unredirected_header("Cookie", cookie_str)

Defensive patterns

Strategy: validation

Validate before calling

# Never set Cookie headers manually; use the cookies parameter
assert 'Cookie' not in request_headers, 'Pass cookies via cookies= param, not headers'

Prevention

Pass cookies via requests.get(url, cookies={'name': 'value'}) or a RequestsCookieJar, never via headers={'Cookie': ...} manipulation through the cookiejar interface
Use session.cookies to persist cookies across requests instead of hand-building Cookie headers
This ValueError comes from urllib2 compatibility shims — avoid calling add_header('Cookie', ...) on the internal MockRequest; use the public cookies API

When it happens

Trigger: A custom or nonstandard CookiePolicy/CookieJar subclass installed on a Requests session that calls request.add_header() during add_cookie_header processing, or user code that grabs the internal MockRequest wrapper and calls add_header() directly. Normal Requests usage never hits it because the stdlib CookieJar only calls add_unredirected_header().

Common situations: Developers writing custom cookie jars or policies (e.g. porting urllib2-era code) that treat the request object as a full urllib.request.Request; test doubles or middleware poking at Requests internals.

Related errors

AI-assisted analysis of psf/requests@414f0513c3 (2026-07-31). Data as JSON: /data/errors/3154592a1005157a.json. Report an issue: GitHub ↗.