{"record":{"id":"b3ac619ba253fa9b","repo":"danny-avila/LibreChat","slug":"path-exceeds-the-maximum-nesting-depth-of-age","errorCode":null,"errorMessage":"${path} exceeds the maximum nesting depth of ${AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH}","messagePattern":"(.+?) exceeds the maximum nesting depth of (.+?)","errorType":"validation","errorClass":"AgentRunEnvelopeError","httpStatus":null,"severity":"error","filePath":"packages/api/src/agents/envelope.ts","lineNumber":102,"sourceCode":"  }\n}\n\nfunction assertNonEmptyString(value: string | undefined, path: string): string {\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    throw new AgentRunEnvelopeError(`${path} must be a non-empty string`);\n  }\n  return value;\n}\n\nfunction cloneJsonValue<T>(value: T, path: string, ancestors: WeakSet<object>, depth: number): T;\nfunction cloneJsonValue(\n  value: unknown,\n  path: string,\n  ancestors: WeakSet<object>,\n  depth: number,\n): unknown {\n  if (depth > AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH) {\n    throw new AgentRunEnvelopeError(\n      `${path} exceeds the maximum nesting depth of ${AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH}`,\n    );\n  }\n\n  if (value === null || typeof value === 'string' || typeof value === 'boolean') {\n    return value;\n  }\n\n  if (typeof value === 'number') {\n    if (!Number.isFinite(value)) {\n      throw new AgentRunEnvelopeError(`${path} must contain only finite numbers`);\n    }\n    return value;\n  }\n\n  if (typeof value !== 'object') {\n    throw new AgentRunEnvelopeError(`${path} contains a non-JSON ${typeof value} value`);\n  }","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/packages/api/src/agents/envelope.ts#L84-L120","documentation":"cloneJsonValue walks the payload recursively to deep-clone it for the transport-safe envelope. If nesting exceeds AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH (64), it throws AgentRunEnvelopeError. The cap prevents stack overflow and rejects pathological/deeply nested payloads that should not cross the execution seam.","triggerScenarios":"Passing a payload whose JSON nesting depth exceeds 64 levels — e.g. a tool result with deeply recursive structure, a document tree, or an accidentally self-referential object that bypassed the circular-reference check via different parents.","commonSituations":"A tool returning a deeply nested API response (e.g. a file-tree dump) inlined into the payload; serialization of ORM objects that nest relations; an adversarial or buggy MCP server emitting depth bombs.","solutions":["Flatten or summarize deeply nested tool results before placing them in the envelope payload.","Validate max depth of tool outputs at the tool boundary, not at envelope construction.","If 64 is too low for a legitimate use case, raise AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH only after confirming stack safety."],"exampleFix":"// before — tool returns a 100-deep tree, inlined into payload\npayload.messages.push({ role: 'tool', content: JSON.stringify(deepTree) });\n\n// after — summarize first\nconst summary = summarizeTree(deepTree, { maxDepth: 10 });\npayload.messages.push({ role: 'tool', content: JSON.stringify(summary) });","handlingStrategy":"validation","validationCode":"const MAX_DEPTH = 64;\nfunction jsonDepth(v: unknown, d = 0): number {\n  if (d > MAX_DEPTH) return d;\n  if (Array.isArray(v)) return Math.max(...v.map((x) => jsonDepth(x, d + 1)), d);\n  if (v && typeof v === 'object') return Math.max(...Object.values(v).map((x) => jsonDepth(x, d + 1)), d);\n  return d;\n}\nif (jsonDepth(payload) > MAX_DEPTH) throw new Error('payload nests too deep');","typeGuard":null,"tryCatchPattern":"import { AgentRunEnvelopeError } from '~/agents/envelope';\ntry {\n  envelope = createAgentRunEnvelope(input);\n} catch (error) {\n  if (error instanceof AgentRunEnvelopeError && /nesting depth/.test(error.message)) {\n    payload.messages = summarizeDeeplyNestedMessages(payload.messages);\n    envelope = createAgentRunEnvelope(input); // retry once\n  } else {\n    throw error;\n  }\n}","preventionTips":["Summarize or flatten deep tool outputs before adding them to the payload.","Validate tool-output depth at the tool boundary.","Treat deep nesting as a smell — likely a tree/file-system dump that does not belong inline."],"tags":["agents","envelope","validation","json","nesting"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}