{"id":"69a57ed60b7867b9","repo":"psf/requests","slug":"you-can-only-merge-into-cookiejar","errorCode":null,"errorMessage":"You can only merge into CookieJar","messagePattern":"You can only merge into CookieJar","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/requests/cookies.py","lineNumber":614,"sourceCode":"        names_from_jar = [cookie.name for cookie in cookiejar]\n        for name in cookie_dict:\n            if overwrite or (name not in names_from_jar):\n                cookiejar.set_cookie(create_cookie(name, cookie_dict[name]))\n\n    return cookiejar\n\n\ndef merge_cookies(\n    cookiejar: CookieJar, cookies: dict[str, str] | CookieJar | None\n) -> CookieJar:\n    \"\"\"Add cookies to cookiejar and returns a merged CookieJar.\n\n    :param cookiejar: CookieJar object to add the cookies to.\n    :param cookies: Dictionary or CookieJar object to be added.\n    :rtype: CookieJar\n    \"\"\"\n    if not isinstance(cookiejar, cookielib.CookieJar):  # runtime guard\n        raise ValueError(\"You can only merge into CookieJar\")\n\n    if isinstance(cookies, dict):\n        cookiejar = cookiejar_from_dict(cookies, cookiejar=cookiejar, overwrite=False)\n    elif isinstance(cookies, cookielib.CookieJar):\n        if update_method := getattr(cookiejar, \"update\", None):\n            update_method(cookies)\n        else:\n            for cookie_in_jar in cookies:\n                cookiejar.set_cookie(cookie_in_jar)\n\n    return cookiejar\n","sourceCodeStart":596,"sourceCodeEnd":626,"githubUrl":"https://github.com/psf/requests/blob/414f0513c33883adf6f2b46901d4f0b38a455851/src/requests/cookies.py#L596-L626","documentation":"A ValueError raised by requests.cookies.merge_cookies() in src/requests/cookies.py. merge_cookies is a runtime guard used when Requests combines session-level and request-level cookies; its first argument must be an http.cookiejar.CookieJar (or subclass such as RequestsCookieJar) to merge into, and anything else — most commonly a plain dict — is rejected immediately.","triggerScenarios":"Assigning a plain dict to session.cookies (session.cookies = {'a': 'b'}) and then making a request, which routes the dict into merge_cookies as the target jar; or calling requests.cookies.merge_cookies(some_dict, other) directly with the arguments effectively swapped (dict target, jar source).","commonSituations":"Developers replacing session.cookies wholesale with a dict instead of using cookiejar_from_dict or session.cookies.update(); helper code that confuses the (cookiejar, cookies) parameter order since the second argument may legitimately be a dict.","solutions":["Never assign a dict to session.cookies; convert first: session.cookies = requests.cookies.cookiejar_from_dict({'a': 'b'}).","Or mutate in place: session.cookies.update({'a': 'b'}) / session.cookies.set('a', 'b').","If calling merge_cookies directly, ensure the first argument is the CookieJar and the second is the dict/jar being merged in."],"exampleFix":"# before\nsession = requests.Session()\nsession.cookies = {'token': 'abc'}\nsession.get(url)  # ValueError\n\n# after\nsession = requests.Session()\nsession.cookies = requests.cookies.cookiejar_from_dict({'token': 'abc'})\nsession.get(url)","handlingStrategy":"type-guard","validationCode":"from http.cookiejar import CookieJar\nassert isinstance(target, CookieJar), 'merge target must be a CookieJar'","typeGuard":"from http.cookiejar import CookieJar\n\ndef can_merge_into(obj):\n    return isinstance(obj, CookieJar)","tryCatchPattern":"try:\n    session.cookies = requests.cookies.merge_cookies(session.cookies, incoming)\nexcept ValueError:\n    jar = requests.cookies.cookiejar_from_dict(incoming)\n    session.cookies = requests.cookies.merge_cookies(session.cookies, jar)","preventionTips":["merge_cookies() requires the first argument to be a CookieJar — dicts are only allowed as the second argument","Convert dicts with requests.cookies.cookiejar_from_dict() before merging or assigning to session.cookies","When passing cookies= to a request, a plain dict is fine; only jar-to-jar merge operations need a real CookieJar target"],"tags":["cookies","cookiejar","valueerror","session","api-misuse"],"analyzedSha":"414f0513c33883adf6f2b46901d4f0b38a455851","analyzedAt":"2026-07-31T19:24:57.696Z","schemaVersion":2}