danny-avila/LibreChat · warning · Error

Subagent graph exceeds the maximum of

Error message

Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.

What it means

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.

Solutions

1. Reduce the number of unique agents referenced across the subagent graph.
2. Consolidate overlapping subagents into fewer agents.
3. Raise MAX_SUBAGENT_GRAPH_NODES only if the larger graph is intentional and resourced.
4. Audit the primary agent's subagent list for accidental or duplicate references.

function assertGraphRoom(agentId, set, max) {
  if (set.has(agentId)) return;
  if (set.size >= max) throw new Error(`Subagent graph cap (${max}) reached`);
}

try { await initializeClient(req, res, endpointOption); }
catch (e) { if (/Subagent graph exceeds the maximum of/.test(e.message)) return res.status(400).json({ error: 'Too many unique subagents' }); throw e; }

When it happens

Trigger: A primary agent whose expanded subagent graph references more unique agents than the configured maximum (after de-duplication via subagentGraphIds).

Common situations: Overly broad subagent configuration referencing many distinct agents; circular or fan-out heavy graphs; a misconfigured agent that lists far more subagents than intended.

Related errors

• Subagent graph exceeds the maximum depth of
• Subagent run configuration exceeds the maximum of
• Subagent changed before it could be initialized.
• Subagent failed model validation.
• You no longer have access to subagent

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/b02b5826f52d1b6c. Report an issue: GitHub.

Appendix: source

Thrown at api/server/services/Endpoints/agents/initialize.js:686

   *  list so agents that already failed handoff loading don't get retried. */
  const skippedAgentIds = new Set(discoveredSkippedIds ?? []);

  const lazyMetadataByAgentId = new Map();
  const subagentGraphIds = new Set();
  const expandedSubagentDescriptorState = { configCount: 0, rootAgentIds: [] };

  const assertSubagentGraphRoom = (agentId) => {
    if (subagentGraphIds.has(agentId)) {
      return;
    }
    if (subagentGraphIds.size >= MAX_SUBAGENT_GRAPH_NODES) {
      logger.warn('[initializeClient] Subagent graph node limit exceeded', {
        agentId,
        primaryAgentId: primaryConfig.id,
        loadedSubagentCount: subagentGraphIds.size,
        maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES,
      });
      throw new Error(
        `Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.`,
      );
    }
  };

  const countExpandedSubagentDescriptor = (agentId) => {
    expandedSubagentDescriptorState.configCount += 1;
    if (expandedSubagentDescriptorState.configCount <= MAX_SUBAGENT_RUN_CONFIGS) {
      return;
    }
    logger.warn('[initializeClient] Subagent run configuration limit exceeded', {
      agentId,
      expandedConfigCount: expandedSubagentDescriptorState.configCount,
      maxSubagentRunConfigs: MAX_SUBAGENT_RUN_CONFIGS,
      rootAgentIds: expandedSubagentDescriptorState.rootAgentIds,
    });
    throw new Error(
      `Subagent run configuration exceeds the maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries.`,

View on GitHub (pinned to 5ff282f900)