NousResearch/hermes-agent · error · SubagentLifecycleError

No active Hermes parent session is available.

Error message

No active Hermes parent session is available.

What it means

Raised by SubagentLifecycleManager.launch() in agent/subagent_lifecycle.py when the parent_agent_resolver() callable returns None — meaning there is no live AIAgent instance to parent the child. Launching a subagent requires an in-process parent session; children cannot be spawned from a detached or dead context.

Source

Thrown at agent/subagent_lifecycle.py:201

    """Return the parent bound to this execution context, if any."""
    return _ACTIVE_PARENT_AGENT.get()


class SubagentLifecycleService:
    """Stable public service returned by :attr:`PluginContext.subagent_lifecycle`.

    Running children are in-process only.  Completed results remain available
    until process exit; ``reconnect`` accurately reports that a serialized
    handle cannot reconnect after a restart instead of launching work again.
    """

    def __init__(self, parent_agent_resolver: Callable[[], Any]) -> None:
        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.

View on GitHub (pinned to c896c09c42)

Solutions

1. Ensure launch() is only called while a parent AIAgent session is active — defer the call until the resolver returns a live agent.
2. Fix the resolver wiring: it must return the currently active agent instance, not a stale reference captured at import time.
3. In tests, install a resolver returning a stub agent (lambda: fake_agent) before calling launch().
4. For work that must run without a live session, use cronjob or terminal(background=True) instead of the subagent lifecycle API.

Example fix

# before
handle = manager.launch(request)  # resolver may return None at startup

# after
parent = get_active_agent()
if parent is None:
    raise RuntimeError("wait for an active Hermes session before launching subagents")
handle = manager.launch(request)

parent = get_active_agent()  # your resolver's source of truth
if parent is None:
    raise RuntimeError("no active Hermes session; cannot launch subagent")
handle = manager.launch(request)

try:
    handle = manager.launch(request)
except SubagentLifecycleError as exc:
    if "No active Hermes parent session" in str(exc):
        queue_for_later_or_fallback()  # e.g. schedule via cronjob
    else:
        raise

When it happens

Trigger: Calling launch() before the Hermes agent/session is initialized; calling it after the parent agent finished or was torn down; wiring a custom parent_agent_resolver that returns None (e.g. reads a module-global set later); invoking the manager from a background thread after session end.

Common situations: Plugin code that captures the lifecycle manager at import time and calls launch() in a cron/webhook path where no interactive session exists; race between session startup and an eager first launch; tests that forget to install a parent agent stub.

Related errors

• parent_session_id does not match the active session.
• Malformed subagent handle.
• Duplicate correlation_id for this parent 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/e2ca21c003ea02c3. Report an issue: GitHub.