D4Vinci/Scrapling · error · ValueError

Session '{session_id}' already registered

Error message

Session '{session_id}' already registered

What it means

SessionManager.add() refuses to register two sessions under the same session_id, raising ValueError to prevent silently replacing an existing session's configuration. Session IDs are the lookup keys used by requests, so duplicates would create ambiguous routing.

Source

Thrown at scrapling/spiders/session.py:31

    """Manages pre-configured session instances."""

    def __init__(self) -> None:
        self._sessions: dict[str, Session] = {}
        self._default_session_id: str | None = None
        self._started: bool = False
        self._lazy_sessions: Set[str] = set()
        self._lazy_lock = Lock()

    def add(self, session_id: str, session: Session, *, default: bool = False, lazy: bool = False) -> "SessionManager":
        """Register a session instance.

        :param session_id: Name to reference this session in requests
        :param session: Your pre-configured session instance
        :param default: If True, this becomes the default session
        :param lazy: If True, the session will be started only when a request uses its ID.
        """
        if session_id in self._sessions:
            raise ValueError(f"Session '{session_id}' already registered")

        self._sessions[session_id] = session

        if default or self._default_session_id is None:
            self._default_session_id = session_id

        if lazy:
            self._lazy_sessions.add(session_id)

        return self

    def remove(self, session_id: str) -> None:
        """Removes a session.

        :param session_id: ID of session to remove
        """
        _ = self.pop(session_id)

View on GitHub (pinned to 5d213a2d47)

Solutions

1. Give each session a unique id: add('browser', camoufox_session) vs add('api', httpx_session).
2. Use pop(session_id) first if intentional replacement is desired, then add() again.
3. Check registration state before adding: if session_id not in manager.session_ids.
4. Audit config files for duplicate session names.

Example fix

# before
manager.add('fetch', session_a)
manager.add('fetch', session_b)  # ValueError

# after
manager.add('fetch', session_a)
manager.add('fetch-2', session_b)

if session_id in manager.session_ids:
    manager.pop(session_id)  # explicit replace policy
manager.add(session_id, session, default=is_default)

try:
    manager.add(session_id, session)
except ValueError as e:
    if 'already registered' in str(e):
        logger.warning('session %r re-registered; replacing', session_id)
        manager.pop(session_id)
        manager.add(session_id, session)
    else:
        raise

When it happens

Trigger: Calling spider/session_manager.add('http', session) twice, or adding sessions with the same name from two different modules/plugins during spider setup.

Common situations: Registering sessions in a loop over a config list that contains a repeated name; a base spider subclass and a plugin both registering a session called 'default'.

Related errors

• Checkpoints interval must be equal or greater than 0.
• No sessions registered
• Session '{session_id}' not found. Available: {available}
• Session type {type(client)} not supported for async fetch
• No session found with the request session id

AI-assisted analysis of D4Vinci/Scrapling@5d213a2d47 (2026-08-14). Data as JSON: /api/errors/4e7c8a5d859eb279. Report an issue: GitHub.