Retired named sessions cannot be replaced, and the session guide says they can

Author: janbucharCreated Sep 18, 2026Updated Sep 18, 2026

Labelst-tooling

SessionPool.addSession({ id }) rejects an existing id before it evicts retired sessions, so once a pinned session (request.sessionId) is retired — block, maxUsageCount, maxAgeSecs — every later request bound to that id fails with MissingSessionError and there is no way to put a replacement under the same id short of reset().
The session management guide ("Pinning a request to a specific session") tells users to "recreate the session via addSession() with the same id"; that throws Cannot add session with id '…' as it already exists. The other option it gives, clearing request.sessionId, works.
Simplest fix is to make the docs true: let addSession({ id }) replace a session under that id when the existing one is no longer usable (retired/expired/exhausted), keeping the throw for a still-usable session so a live cookie jar is not swapped out by accident. A removeSession(id) would cover the remaining cases but is not needed for the documented flow.
Cosmetic, same code path: the retry wrapper around getSession logs WARN CheerioCrawler: (retrying 1/3) with an empty message on every miss.

Source: apify/crawlee