NousResearch/hermes-agent · error · SubagentLifecycleError

goal must be a non-empty string of at most 16000 characters.

Error message

goal must be a non-empty string of at most 16000 characters.

What it means

Validation error from SubagentLifecycleManager._validate_request(): the goal field of SubagentLaunchRequest must be a non-empty, non-whitespace string no longer than _MAX_GOAL_CHARS (16000). It rejects empty goals, non-string goals, whitespace-only goals, and oversized goals before any child is spawned.

Source

Thrown at agent/subagent_lifecycle.py:494

            record.completed_at = result.completed_at
            record.updated_at = result.completed_at or time.time()

    @staticmethod
    def _capability(
        subagent_id: str, parent_session_id: Optional[str], created_at: float
    ) -> str:
        value = f"{subagent_id}|{parent_session_id or ''}|{created_at:.6f}".encode()
        return hmac.new(_SECRET, value, hashlib.sha256).hexdigest()

    @staticmethod
    def _validate_request(request: SubagentLaunchRequest, parent: Any) -> None:
        if (
            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."

View on GitHub (pinned to c896c09c42)

Solutions

  1. Trim and check the goal before launching: require a non-empty str within the limit.
  2. Move large reference material into the context field (limit 32000 chars) or a file the child can read, keeping the goal short.
  3. Coerce non-string input explicitly (str(...) on validated data) or reject it at your API boundary.

Example fix

# before
request = SubagentLaunchRequest(goal=raw_user_input)

# after
goal = (raw_user_input or "").strip() if isinstance(raw_user_input, str) else ""
if not goal:
    raise ValueError("goal required")
request = SubagentLaunchRequest(goal=goal[:16000])
Defensive patterns

Strategy: validation

Validate before calling

MAX_GOAL = 16000
goal = goal if isinstance(goal, str) else ""
goal = goal.strip()
assert goal and len(goal) <= MAX_GOAL, "goal must be 1..16000 chars of text"
request = SubagentLaunchRequest(goal=goal)

Type guard

def is_valid_goal(value: object) -> bool:
    return isinstance(value, str) and bool(value.strip()) and len(value) <= 16000

Try / catch

try:
    manager.launch(request)
except SubagentLifecycleError as exc:
    if "goal must be" in str(exc):
        raise ValueError("invalid goal from upstream") from exc
    raise

Prevention

When it happens

Trigger: Calling launch() with goal="", goal=None, goal=" ", goal containing 16000+ characters, or a goal that is a list/dict because the caller forgot to serialize structured input to text.

Common situations: Passing raw user input that may be empty (e.g. an empty webhook payload mapped straight to goal); concatenating huge documents into the goal instead of the context field; forwarding a non-string prompt from an upstream API.

Related errors

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