{"record":{"id":"b02b5826f52d1b6c","repo":"danny-avila/LibreChat","slug":"subagent-graph-exceeds-the-maximum-of-max-subage","errorCode":null,"errorMessage":"Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.","messagePattern":"Subagent graph exceeds the maximum of (.+?) unique agents\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"api/server/services/Endpoints/agents/initialize.js","lineNumber":686,"sourceCode":"   *  list so agents that already failed handoff loading don't get retried. */\n  const skippedAgentIds = new Set(discoveredSkippedIds ?? []);\n\n  const lazyMetadataByAgentId = new Map();\n  const subagentGraphIds = new Set();\n  const expandedSubagentDescriptorState = { configCount: 0, rootAgentIds: [] };\n\n  const assertSubagentGraphRoom = (agentId) => {\n    if (subagentGraphIds.has(agentId)) {\n      return;\n    }\n    if (subagentGraphIds.size >= MAX_SUBAGENT_GRAPH_NODES) {\n      logger.warn('[initializeClient] Subagent graph node limit exceeded', {\n        agentId,\n        primaryAgentId: primaryConfig.id,\n        loadedSubagentCount: subagentGraphIds.size,\n        maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES,\n      });\n      throw new Error(\n        `Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.`,\n      );\n    }\n  };\n\n  const countExpandedSubagentDescriptor = (agentId) => {\n    expandedSubagentDescriptorState.configCount += 1;\n    if (expandedSubagentDescriptorState.configCount <= MAX_SUBAGENT_RUN_CONFIGS) {\n      return;\n    }\n    logger.warn('[initializeClient] Subagent run configuration limit exceeded', {\n      agentId,\n      expandedConfigCount: expandedSubagentDescriptorState.configCount,\n      maxSubagentRunConfigs: MAX_SUBAGENT_RUN_CONFIGS,\n      rootAgentIds: expandedSubagentDescriptorState.rootAgentIds,\n    });\n    throw new Error(\n      `Subagent run configuration exceeds the maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries.`,","sourceCodeStart":668,"sourceCodeEnd":704,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/api/server/services/Endpoints/agents/initialize.js#L668-L704","documentation":"Thrown by assertSubagentGraphRoom when adding a new unique agent id would push the subagent graph past MAX_SUBAGENT_GRAPH_NODES distinct agents. This is a protective guard against combinatorial explosion in agent delegation graphs.","triggerScenarios":"A primary agent whose expanded subagent graph references more unique agents than the configured maximum (after de-duplication via subagentGraphIds).","commonSituations":"Overly broad subagent configuration referencing many distinct agents; circular or fan-out heavy graphs; a misconfigured agent that lists far more subagents than intended.","solutions":["Reduce the number of unique agents referenced across the subagent graph.","Consolidate overlapping subagents into fewer agents.","Raise MAX_SUBAGENT_GRAPH_NODES only if the larger graph is intentional and resourced.","Audit the primary agent's subagent list for accidental or duplicate references."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"function assertGraphRoom(agentId, set, max) {\n  if (set.has(agentId)) return;\n  if (set.size >= max) throw new Error(`Subagent graph cap (${max}) reached`);\n}","typeGuard":null,"tryCatchPattern":"try { await initializeClient(req, res, endpointOption); }\ncatch (e) { if (/Subagent graph exceeds the maximum of/.test(e.message)) return res.status(400).json({ error: 'Too many unique subagents' }); throw e; }","preventionTips":["Keep subagent lists short and de-duplicated.","Document the cap for agent authors.","Audit graphs during authoring, not just at request time."],"tags":["agents","subagents","limits","graph"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}