{"record":{"id":"8ceed5e99340a2a4","repo":"NousResearch/hermes-agent","slug":"metadata-exceeds-8192-bytes","errorCode":null,"errorMessage":"metadata exceeds 8192 bytes.","messagePattern":"metadata exceeds 8192 bytes\\.","errorType":"exception","errorClass":"SubagentLifecycleError","httpStatus":null,"severity":"error","filePath":"agent/subagent_lifecycle.py","lineNumber":525,"sourceCode":"            raise SubagentLifecycleError(\n                \"Per-launch timeout is not supported; configure delegation timeout explicitly.\"\n            )\n        if request.working_directory is not None:\n            raise SubagentLifecycleError(\n                \"working_directory is not supported because Hermes delegates use isolated task environments.\"\n            )\n        if request.blocked_tools:\n            raise SubagentLifecycleError(\n                \"Per-tool blocking is not supported; use allowed_toolsets. Hermes always blocks unsafe child tools.\"\n            )\n        try:\n            metadata_bytes = len(\n                json.dumps(dict(request.metadata), sort_keys=True).encode()\n            )\n        except (TypeError, ValueError) as exc:\n            raise SubagentLifecycleError(\"metadata must be JSON-serializable.\") from exc\n        if metadata_bytes > _MAX_METADATA_BYTES:\n            raise SubagentLifecycleError(\"metadata exceeds 8192 bytes.\")\n        if request.allowed_toolsets:\n            from toolsets import TOOLSETS\n\n            unknown = set(request.allowed_toolsets) - set(TOOLSETS)\n            if unknown:\n                raise SubagentLifecycleError(\n                    f\"Unknown toolsets: {', '.join(sorted(unknown))}.\"\n                )\n            enabled = getattr(parent, \"enabled_toolsets\", None)\n            if enabled is not None and not set(request.allowed_toolsets).issubset(\n                set(enabled)\n            ):\n                raise SubagentLifecycleError(\n                    \"Requested toolsets would broaden parent permissions.\"\n                )\n","sourceCodeStart":507,"sourceCodeEnd":541,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/subagent_lifecycle.py#L507-L541","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move large payloads out of metadata — store them (file, DB, object storage) and put a reference id/URL in metadata.","Trim metadata to essential scalar fields; if tracing, keep a correlation id and fetch details from your own store.","Compute the same measurement before launch: len(json.dumps(metadata, sort_keys=True).encode()) <= 8192."],"exampleFix":"# before\nrequest = SubagentLaunchRequest(goal=g, metadata={\"doc\": base64.b64encode(pdf_bytes).decode()})\n\n# after\nref = store.put(pdf_bytes)\nrequest = SubagentLaunchRequest(goal=g, metadata={\"doc_ref\": ref})","handlingStrategy":"validation","validationCode":"import json\nMAX_METADATA_BYTES = 8192\nsize = len(json.dumps(metadata, sort_keys=True).encode())\nif size > MAX_METADATA_BYTES:\n    metadata = {\"ref\": store_payload_and_return_ref(metadata)}\nrequest = SubagentLaunchRequest(goal=goal, metadata=metadata)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Measure bytes (encode()), not characters — multibyte content inflates size.","Store large payloads out-of-band and keep only a reference id in metadata.","Compute the exact same json.dumps(sort_keys=True) size check before launching."],"tags":["subagents","delegation","validation","metadata","size-limit"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}