{"id":"3154592a1005157a","repo":"psf/requests","slug":"cookie-headers-should-be-added-with-add-unredirect","errorCode":null,"errorMessage":"Cookie headers should be added with add_unredirected_header()","messagePattern":"Cookie headers should be added with add_unredirected_header\\(\\)","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"warning","filePath":"src/requests/cookies.py","lineNumber":91,"sourceCode":"                parsed.path,\n                parsed.params,\n                parsed.query,\n                parsed.fragment,\n            ]\n        )\n\n    def is_unverifiable(self) -> bool:\n        return True\n\n    def has_header(self, name: str) -> bool:\n        return name in self._r.headers or name in self._new_headers\n\n    def get_header(self, name: str, default: str | None = None) -> str | None:\n        return self._r.headers.get(name, self._new_headers.get(name, default))  # type: ignore[return-value]\n\n    def add_header(self, key: str, val: str) -> None:\n        \"\"\"cookiejar has no legitimate use for this method; add it back if you find one.\"\"\"\n        raise NotImplementedError(\n            \"Cookie headers should be added with add_unredirected_header()\"\n        )\n\n    def add_unredirected_header(self, name: str, value: str) -> None:\n        self._new_headers[name] = value\n\n    def get_new_headers(self) -> dict[str, str]:\n        return self._new_headers\n\n    @property\n    def unverifiable(self) -> bool:\n        return self.is_unverifiable()\n\n    @property\n    def origin_req_host(self) -> str:\n        return self.get_origin_req_host()\n\n    @property","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/psf/requests/blob/414f0513c33883adf6f2b46901d4f0b38a455851/src/requests/cookies.py#L73-L109","documentation":"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').","triggerScenarios":"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().","commonSituations":"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.","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."],"exampleFix":"# before (custom cookie policy)\nrequest.add_header(\"Cookie\", cookie_str)\n\n# after\nrequest.add_unredirected_header(\"Cookie\", cookie_str)","handlingStrategy":"validation","validationCode":"# Never set Cookie headers manually; use the cookies parameter\nassert 'Cookie' not in request_headers, 'Pass cookies via cookies= param, not headers'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cookies","cookiejar","internal-api","not-implemented"],"analyzedSha":"414f0513c33883adf6f2b46901d4f0b38a455851","analyzedAt":"2026-07-31T19:24:57.696Z","schemaVersion":2}