psf/requests · error · ValueError

You can only merge into CookieJar

Error message

You can only merge into CookieJar

What it means

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.

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 414f0513c3)

Solutions

1. Never assign a dict to session.cookies; convert first: session.cookies = requests.cookies.cookiejar_from_dict({'a': 'b'}).
2. Or mutate in place: session.cookies.update({'a': 'b'}) / session.cookies.set('a', 'b').
3. If calling merge_cookies directly, ensure the first argument is the CookieJar and the second is the dict/jar being merged in.

Example fix

# before
session = requests.Session()
session.cookies = {'token': 'abc'}
session.get(url)  # ValueError

# after
session = requests.Session()
session.cookies = requests.cookies.cookiejar_from_dict({'token': 'abc'})
session.get(url)

from http.cookiejar import CookieJar
assert isinstance(target, CookieJar), 'merge target must be a CookieJar'

from http.cookiejar import CookieJar

def can_merge_into(obj):
    return isinstance(obj, CookieJar)

try:
    session.cookies = requests.cookies.merge_cookies(session.cookies, incoming)
except ValueError:
    jar = requests.cookies.cookiejar_from_dict(incoming)
    session.cookies = requests.cookies.merge_cookies(session.cookies, jar)

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Cookie headers should be added with add_unredirected_header(
• name={name!r}, domain={domain!r}, path={path!r}
• There are multiple cookies with name, {name!r}
• create_cookie() got unexpected keyword arguments: {list(bada
• Exceeded {self.max_redirects} redirects.

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