{"record":{"id":"e2ca21c003ea02c3","repo":"NousResearch/hermes-agent","slug":"no-active-hermes-parent-session-is-available","errorCode":null,"errorMessage":"No active Hermes parent session is available.","messagePattern":"No active Hermes parent session is available\\.","errorType":"exception","errorClass":"SubagentLifecycleError","httpStatus":null,"severity":"error","filePath":"agent/subagent_lifecycle.py","lineNumber":201,"sourceCode":"    \"\"\"Return the parent bound to this execution context, if any.\"\"\"\n    return _ACTIVE_PARENT_AGENT.get()\n\n\nclass SubagentLifecycleService:\n    \"\"\"Stable public service returned by :attr:`PluginContext.subagent_lifecycle`.\n\n    Running children are in-process only.  Completed results remain available\n    until process exit; ``reconnect`` accurately reports that a serialized\n    handle cannot reconnect after a restart instead of launching work again.\n    \"\"\"\n\n    def __init__(self, parent_agent_resolver: Callable[[], Any]) -> None:\n        self._parent_agent_resolver = parent_agent_resolver\n\n    def launch(self, request: SubagentLaunchRequest) -> SubagentHandle:\n        parent = self._parent_agent_resolver()\n        if parent is None:\n            raise SubagentLifecycleError(\n                \"No active Hermes parent session is available.\"\n            )\n        self._validate_request(request, parent)\n        parent_session_id = str(getattr(parent, \"session_id\", \"\") or \"\") or None\n        if request.parent_session_id and request.parent_session_id != parent_session_id:\n            raise SubagentLifecycleError(\n                \"parent_session_id does not match the active session.\"\n            )\n        correlation_key = (parent_session_id, request.correlation_id or \"\")\n        with _REGISTRY.lock:\n            self._cleanup_locked()\n            if request.correlation_id and correlation_key in _REGISTRY.correlations:\n                raise SubagentLifecycleError(\n                    \"Duplicate correlation_id for this parent session.\"\n                )\n\n        # Delegate construction remains internal so plugin code never imports\n        # private delegation helpers or manipulates the active-child registry.","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/subagent_lifecycle.py#L183-L219","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure launch() is only called while a parent AIAgent session is active — defer the call until the resolver returns a live agent.","Fix the resolver wiring: it must return the currently active agent instance, not a stale reference captured at import time.","In tests, install a resolver returning a stub agent (lambda: fake_agent) before calling launch().","For work that must run without a live session, use cronjob or terminal(background=True) instead of the subagent lifecycle API."],"exampleFix":"# before\nhandle = manager.launch(request)  # resolver may return None at startup\n\n# after\nparent = get_active_agent()\nif parent is None:\n    raise RuntimeError(\"wait for an active Hermes session before launching subagents\")\nhandle = manager.launch(request)","handlingStrategy":"validation","validationCode":"parent = get_active_agent()  # your resolver's source of truth\nif parent is None:\n    raise RuntimeError(\"no active Hermes session; cannot launch subagent\")\nhandle = manager.launch(request)","typeGuard":null,"tryCatchPattern":"try:\n    handle = manager.launch(request)\nexcept SubagentLifecycleError as exc:\n    if \"No active Hermes parent session\" in str(exc):\n        queue_for_later_or_fallback()  # e.g. schedule via cronjob\n    else:\n        raise","preventionTips":["Only call launch() from code that runs inside a live agent session.","Make parent_agent_resolver read the current agent, not an import-time capture.","For session-independent work, use cronjob or terminal(background=True) instead of the subagent lifecycle API."],"tags":["subagents","delegation","session","lifecycle"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}