danny-avila/LibreChat · warning · Error

Subagent graph exceeds the maximum depth of ${MAX_SUBAGENT_D

Error message

Subagent graph exceeds the maximum depth of ${MAX_SUBAGENT_DEPTH} at agent ${agent.id}.

What it means

Thrown when expanding a subagent graph node that itself declares subagents at a depth already equal to MAX_SUBAGENT_DEPTH. This prevents unboundedly deep delegation chains that could recurse or stack deeply.

Source

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

    return config;
  };

  const buildLazySubagentDescriptors = async (agent, depth = 0, ancestors = new Set()) => {
    if (!subagentsCapabilityEnabled || !agent.subagents?.enabled) {
      return [];
    }
    if (agent.subagents.allowSelf !== false) {
      countExpandedSubagentDescriptor(agent.id);
    }
    const subagentIds = getExplicitSubagentIds(agent);
    if (subagentIds.length > 0 && depth >= MAX_SUBAGENT_DEPTH) {
      logger.warn('[initializeClient] Subagent graph depth limit exceeded', {
        agentId: agent.id,
        primaryAgentId: primaryConfig.id,
        depth,
        maxSubagentDepth: MAX_SUBAGENT_DEPTH,
      });
      throw new Error(
        `Subagent graph exceeds the maximum depth of ${MAX_SUBAGENT_DEPTH} at agent ${agent.id}.`,
      );
    }
    const nextAncestors = new Set(ancestors);
    nextAncestors.add(agent.id);
    const descriptors = [];
    for (const subagentId of subagentIds) {
      if (skippedAgentIds.has(subagentId) || nextAncestors.has(subagentId)) continue;
      if (subagentId !== primaryConfig.id) {
        assertSubagentGraphRoom(subagentId);
      }
      const existing =
        subagentId === primaryConfig.id ? primaryConfig : agentConfigs.get(subagentId);
      if (existing) {
        countExpandedSubagentDescriptor(subagentId);
        if (subagentId !== primaryConfig.id) {
          subagentGraphIds.add(subagentId);
        }

View on GitHub (pinned to 5ff282f900)

Solutions

Flatten the delegation chain so no path exceeds the maximum depth.
Remove deep or self-referential subagent edges (set allowSelf:false where appropriate).
Raise MAX_SUBAGENT_DEPTH only if a deeper chain is intentional and safe.
Audit agent definitions for unintended transitive references.

Defensive patterns

Strategy: validation

Validate before calling

if (subagentIds.length > 0 && depth >= MAX_SUBAGENT_DEPTH) {
  throw new Error(`Depth cap (${MAX_SUBAGENT_DEPTH}) reached at ${agent.id}`);
}

Try / catch

try { await initializeClient(req, res, endpointOption); }
catch (e) { if (/maximum depth/.test(e.message)) return res.status(400).json({ error: 'Subagent nesting too deep' }); throw e; }

Prevention

Avoid self-referential or cyclic subagent edges.
Flatten delegation chains in agent design.
Warn authors in the UI when a graph approaches the depth cap.

When it happens

Trigger: A chain of agents A->B->C->... where each delegates to the next, and the deepest agent still declares further subagents at the configured depth ceiling.

Common situations: Agents referencing each other transitively; a template agent that always lists itself or a long chain as a subagent; deep organizational delegation modeled as nested agents.

Related errors

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