danny-avila/LibreChat · warning · Error

Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_N

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.

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)

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.

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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; }

Prevention

Keep subagent lists short and de-duplicated.
Document the cap for agent authors.
Audit graphs during authoring, not just at request time.

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

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