psf/requests · error · ValueError

You can only merge into CookieJar

Error message

You can only merge into CookieJar

What it means

Raised by merge_cookies when its first argument is not an instance of http.cookiejar.CookieJar. The function's contract is to add cookies into an existing jar, so a non-jar (e.g. a dict, list, or None passed as the jar) is rejected. This is a defensive runtime guard added because silently coercing would hide caller bugs.

Solutions

1. Pass an actual session.cookies (a RequestsCookieJar, which subclasses CookieJar) or create one with requests.cookies.cookiejar_from_dict({}).
2. If you have a dict, call merge_cookies(session.cookies, my_dict) — the dict belongs in the second argument.
3. Type-check the first argument with isinstance(jar, http.cookiejar.CookieJar) before calling.

Example fix

// before
merge_cookies({}, {'sid': 'x'})

// after
import requests.cookies as rc
jar = rc.cookiejar_from_dict({})
merge_cookies(jar, {'sid': 'x'})

import http.cookiejar
from requests.cookies import merge_cookies

def safe_merge(jar, cookies):
    if not isinstance(jar, http.cookiejar.CookieJar):
        raise TypeError('first argument must be a http.cookiejar.CookieJar')
    return merge_cookies(jar, cookies)

import http.cookiejar

def is_cookiejar(obj) -> bool:
    return isinstance(obj, http.cookiejar.CookieJar)

import http.cookiejar
from requests.cookies import merge_cookies, cookiejar_from_dict

if not isinstance(myjar, http.cookiejar.CookieJar):
    myjar = cookiejar_from_dict({})
merge_cookies(myjar, cookies)

When it happens

Trigger: Passing a dict or list as the first positional arg to merge_cookies (e.g. merge_cookies({}, cookies)); passing None because the caller forgot to initialize a session cookiejar; passing a custom object that does not subclass cookielib.CookieJar.

Common situations: Refactor where a session was replaced by a plain dict; threading cookies through a helper that lost the session reference; library wrappers that accept 'a jar-like object' but actually require a real CookieJar.

Related errors

• Cookie headers should be added with…
• create_cookie() got unexpected keyword arguments
• Files must be provided.
• name= , domain= , path=
• There are multiple cookies with name

AI-assisted analysis of psf/requests@8068356288 (2026-08-11). Data as JSON: /api/errors/69a57ed60b7867b9. Report an issue: GitHub.

Appendix: source

Thrown at src/requests/cookies.py:614

        names_from_jar = [cookie.name for cookie in cookiejar]
        for name in cookie_dict:
            if overwrite or (name not in names_from_jar):
                cookiejar.set_cookie(create_cookie(name, cookie_dict[name]))

    return cookiejar


def merge_cookies(
    cookiejar: CookieJar, cookies: dict[str, str] | CookieJar | None
) -> CookieJar:
    """Add cookies to cookiejar and returns a merged CookieJar.

    :param cookiejar: CookieJar object to add the cookies to.
    :param cookies: Dictionary or CookieJar object to be added.
    :rtype: CookieJar
    """
    if not isinstance(cookiejar, cookielib.CookieJar):  # runtime guard
        raise ValueError("You can only merge into CookieJar")

    if isinstance(cookies, dict):
        cookiejar = cookiejar_from_dict(cookies, cookiejar=cookiejar, overwrite=False)
    elif isinstance(cookies, cookielib.CookieJar):
        if update_method := getattr(cookiejar, "update", None):
            update_method(cookies)
        else:
            for cookie_in_jar in cookies:
                cookiejar.set_cookie(cookie_in_jar)

    return cookiejar

View on GitHub (pinned to 8068356288)