NousResearch/hermes-agent · error · SubagentLifecycleError

Per-launch timeout is not supported; configure delegation ti

Error message

Per-launch timeout is not supported; configure delegation timeout explicitly.

What it means

Validation error from SubagentLifecycleManager._validate_request(): per-launch timeouts are deliberately not part of the subagent lifecycle contract. If request.timeout_seconds is not None the launch is rejected with a pointer to the global delegation timeout configuration — child timeouts must be configured at the delegation level, not per launch.

Source

Thrown at agent/subagent_lifecycle.py:507

            not isinstance(request, SubagentLaunchRequest)
            or not isinstance(request.goal, str)
            or not request.goal.strip()
            or len(request.goal) > _MAX_GOAL_CHARS
        ):
            raise SubagentLifecycleError(
                "goal must be a non-empty string of at most 16000 characters."
            )
        if request.context is not None and (
            not isinstance(request.context, str)
            or len(request.context) > _MAX_CONTEXT_CHARS
        ):
            raise SubagentLifecycleError(
                "context must be a string of at most 32000 characters."
            )
        if request.role not in {"leaf", "orchestrator"}:
            raise SubagentLifecycleError("role must be 'leaf' or 'orchestrator'.")
        if request.timeout_seconds is not None:
            raise SubagentLifecycleError(
                "Per-launch timeout is not supported; configure delegation timeout explicitly."
            )
        if request.working_directory is not None:
            raise SubagentLifecycleError(
                "working_directory is not supported because Hermes delegates use isolated task environments."
            )
        if request.blocked_tools:
            raise SubagentLifecycleError(
                "Per-tool blocking is not supported; use allowed_toolsets. Hermes always blocks unsafe child tools."
            )
        try:
            metadata_bytes = len(
                json.dumps(dict(request.metadata), sort_keys=True).encode()
            )
        except (TypeError, ValueError) as exc:
            raise SubagentLifecycleError("metadata must be JSON-serializable.") from exc
        if metadata_bytes > _MAX_METADATA_BYTES:
            raise SubagentLifecycleError("metadata exceeds 8192 bytes.")

View on GitHub (pinned to c896c09c42)

Solutions

1. Remove timeout_seconds from the request (leave it None) and set the global cap via delegation.child_timeout_seconds in config.yaml.
2. If you need per-task time bounds, enforce them yourself by polling the child's status and abandoning/ignoring results past a deadline.
3. Audit request-construction helpers so optional numerics default to None, not 0.

Example fix

# before
request = SubagentLaunchRequest(goal=g, timeout_seconds=120)

# after
# config.yaml: delegation: child_timeout_seconds: 120
request = SubagentLaunchRequest(goal=g)

request = SubagentLaunchRequest(goal=goal)  # timeout_seconds omitted -> None
# enforce per-task deadlines yourself:
deadline = time.monotonic() + 120

try:
    manager.launch(request)
except SubagentLifecycleError as exc:
    if "Per-launch timeout" in str(exc):
        request = dataclasses.replace(request, timeout_seconds=None)
        manager.launch(request)
    else:
        raise

When it happens

Trigger: Setting SubagentLaunchRequest(timeout_seconds=300); porting code from an async-subagent API that accepted per-task timeouts; SDK-generated request objects that populate every optional field with a default number instead of None.

Common situations: Autofilling serializers (e.g. protobuf/thrift defaults of 0 that become non-None); copying a request template from another tool; trying to bound a risky child individually.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• parent_session_id does not match the active session.
• goal must be a non-empty string of at most 16000 characters.
• context must be a string of at most 32000 characters.
• role must be 'leaf' or 'orchestrator'.
• working_directory is not supported because Hermes delegates

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