NousResearch/hermes-agent · error · SubagentLifecycleError

metadata exceeds 8192 bytes.

Error message

metadata exceeds 8192 bytes.

What it means

Validation error from SubagentLifecycleManager._validate_request(): the JSON encoding of request.metadata (sort_keys=True, compact measurement via len of encoded bytes) must be at most _MAX_METADATA_BYTES (8192 bytes). It bounds how much bookkeeping data can ride along with a launch.

Source

Thrown at agent/subagent_lifecycle.py:525

            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.")
        if request.allowed_toolsets:
            from toolsets import TOOLSETS

            unknown = set(request.allowed_toolsets) - set(TOOLSETS)
            if unknown:
                raise SubagentLifecycleError(
                    f"Unknown toolsets: {', '.join(sorted(unknown))}."
                )
            enabled = getattr(parent, "enabled_toolsets", None)
            if enabled is not None and not set(request.allowed_toolsets).issubset(
                set(enabled)
            ):
                raise SubagentLifecycleError(
                    "Requested toolsets would broaden parent permissions."
                )

View on GitHub (pinned to c896c09c42)

Solutions

1. Move large payloads out of metadata — store them (file, DB, object storage) and put a reference id/URL in metadata.
2. Trim metadata to essential scalar fields; if tracing, keep a correlation id and fetch details from your own store.
3. Compute the same measurement before launch: len(json.dumps(metadata, sort_keys=True).encode()) <= 8192.

Example fix

# before
request = SubagentLaunchRequest(goal=g, metadata={"doc": base64.b64encode(pdf_bytes).decode()})

# after
ref = store.put(pdf_bytes)
request = SubagentLaunchRequest(goal=g, metadata={"doc_ref": ref})

import json
MAX_METADATA_BYTES = 8192
size = len(json.dumps(metadata, sort_keys=True).encode())
if size > MAX_METADATA_BYTES:
    metadata = {"ref": store_payload_and_return_ref(metadata)}
request = SubagentLaunchRequest(goal=goal, metadata=metadata)

When it happens

Trigger: Attaching base64 blobs, full stack traces, long descriptions, or large id lists as metadata; metadata that grew through iterative debugging additions; UTF-8 multibyte content inflating byte count past the limit even when under 8192 characters.

Common situations: Embedding payloads (images, documents, logs) in metadata instead of storing them out-of-band and passing an id/reference; copying request/response bodies into metadata for tracing; forgetting the limit counts bytes, not characters.

Related errors

• metadata must be JSON-serializable.
• 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'.

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