NousResearch/hermes-agent · error · SubagentLifecycleError

Duplicate correlation_id for this parent session.

Error message

Duplicate correlation_id for this parent session.

What it means

Raised by SubagentLifecycleManager.launch() when a launch request carries a correlation_id whose (parent_session_id, correlation_id) key is already registered and not yet cleaned up. It prevents two live children being correlated to the same logical task within one parent session.

Source

Thrown at agent/subagent_lifecycle.py:214

        self._parent_agent_resolver = parent_agent_resolver

    def launch(self, request: SubagentLaunchRequest) -> SubagentHandle:
        parent = self._parent_agent_resolver()
        if parent is None:
            raise SubagentLifecycleError(
                "No active Hermes parent session is available."
            )
        self._validate_request(request, parent)
        parent_session_id = str(getattr(parent, "session_id", "") or "") or None
        if request.parent_session_id and request.parent_session_id != parent_session_id:
            raise SubagentLifecycleError(
                "parent_session_id does not match the active session."
            )
        correlation_key = (parent_session_id, request.correlation_id or "")
        with _REGISTRY.lock:
            self._cleanup_locked()
            if request.correlation_id and correlation_key in _REGISTRY.correlations:
                raise SubagentLifecycleError(
                    "Duplicate correlation_id for this parent session."
                )

        # Delegate construction remains internal so plugin code never imports
        # private delegation helpers or manipulates the active-child registry.
        from tools.delegate_tool import (
            _build_child_preserving_parent_tools,
            DEFAULT_MAX_ITERATIONS,
        )

        child = _build_child_preserving_parent_tools(
            task_index=0,
            goal=request.goal,
            context=request.context,
            toolsets=list(request.allowed_toolsets)
            if request.allowed_toolsets
            else None,
            model=request.model,

View on GitHub (pinned to c896c09c42)

Solutions

1. Generate a fresh correlation_id (e.g. uuid4().hex) for every launch attempt, including retries.
2. If idempotency-by-correlation-id is desired, first check the existing entry's state (poll/wait for completion) instead of launching again — completed entries are pruned by cleanup, after which the id is reusable.
3. Log the correlation_id at launch so duplicates can be traced to their first owner.

Example fix

# before
request = SubagentLaunchRequest(goal=g, correlation_id=event_id)
handle = manager.launch(request)  # second delivery of event -> duplicate

# after
import uuid
request = SubagentLaunchRequest(goal=g, correlation_id=f"{event_id}:{uuid.uuid4().hex[:8]}")
handle = manager.launch(request)

import uuid
request = SubagentLaunchRequest(
    goal=goal,
    correlation_id=uuid.uuid4().hex,  # unique per attempt, not per logical event
)

try:
    handle = manager.launch(request)
except SubagentLifecycleError as exc:
    if "Duplicate correlation_id" in str(exc):
        request = dataclasses.replace(request, correlation_id=uuid.uuid4().hex)
        handle = manager.launch(request)
    else:
        raise

When it happens

Trigger: Launching twice with the same correlation_id while the first child is still running (or its registry entry has not been reaped); reusing an id generator that repeats after a crash; firing a webhook handler twice for the same event and mapping event-id to correlation_id.

Common situations: Retries of a failed launch that reuse the request verbatim; at-least-once delivery from a queue where the same message triggers two launches; generating correlation ids from timestamps with second granularity causing collisions.

Related errors

• Malformed subagent handle.
• No active Hermes parent session is available.
• parent_session_id does not match the active session.
• Hermes failed to assign a child identity.
• goal must be a non-empty string of at most 16000 characters.

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/5395f1fdaad075da. Report an issue: GitHub.