mermaid-js/mermaid · error · Error

There can be only one root. No parent could be found for ("$

Error message

There can be only one root. No parent could be found for ("${node.descr}")

What it means

Thrown by addNode in the mindmap db when a non-root node cannot find a parent at level-1 via getParent. Mindmaps require exactly one root node; every other node must have a parent one level shallower. If a node is declared at a depth with no existing ancestor at depth-1, and it is not itself the root, the tree is malformed and the build aborts.

Source

Thrown at packages/mermaid/src/diagrams/mindmap/mindmapDb.ts:120

      nodeId: sanitizeText(id, conf),
      level,
      descr: sanitizeText(descr, conf),
      type,
      children: [],
      width: conf.mindmap?.maxNodeWidth ?? defaultConfig.mindmap.maxNodeWidth,
      padding,
      isRoot,
    };

    const parent = this.getParent(level);
    if (parent) {
      parent.children.push(node);
      this.nodes.push(node);
    } else {
      if (isRoot) {
        this.nodes.push(node);
      } else {
        throw new Error(
          `There can be only one root. No parent could be found for ("${node.descr}")`
        );
      }
    }
  }

  public getType(startStr: string, endStr: string) {
    log.debug('In get type', startStr, endStr);
    switch (startStr) {
      case '[':
        return this.nodeType.RECT;
      case '(':
        return endStr === ')' ? this.nodeType.ROUNDED_RECT : this.nodeType.CLOUD;
      case '((':
        return this.nodeType.CIRCLE;
      case ')':
        return this.nodeType.CLOUD;
      case '))':

View on GitHub (pinned to d93e9c88c0)

Solutions

Ensure exactly one node sits at the top level (the root) and every other node is indented exactly one level deeper than its parent.
Normalize indentation to consistent spaces and verify no level is skipped.
Start the mindmap with the root node on its own line, then add children one indent level at a time.
If nesting deeply, build incrementally and render after each level to catch the error early.

Example fix

// before — child jumps two levels, no intermediate parent
mindmap
  root
      deeply_nested_child

// after
mindmap
  root
    child
      deeply_nested_child

Defensive patterns

Strategy: validation

Validate before calling

// Validate mindmap tree depth: each node's level may be at most parentLevel+1.
function validateMindmapDepth(nodes: {level:number;descr:string}[]): string[] {
  const errors: string[] = [];
  let prevLevel = nodes[0]?.level ?? 0;
  for (const n of nodes.slice(1)) {
    if (n.level > prevLevel + 1) {
      errors.push(`Node '${n.descr}' skips a level (got ${n.level}, expected <= ${prevLevel + 1})`);
    }
    prevLevel = n.level;
  }
  return errors;
}

Try / catch

try {
  await mermaid.render('g', diagramText);
} catch (e) {
  if (e instanceof Error && /There can be only one root/.test(e.message)) {
    showUserError('Your mindmap has a node with no parent. Ensure exactly one root and indent children one level at a time.');
  } else {
    throw e;
  }
}

Prevention

Declare exactly one root node at the top level.
Indent each child exactly one level deeper than its parent — never skip a level.
Use consistent spacing for indentation.

When it happens

Trigger: Indenting a node two levels deeper than its parent (skipping a level); declaring a second root-level node; starting the mindmap body with a deeply indented node before any root.

Common situations: Using tabs vs spaces inconsistently so the parser computes wrong levels; copy-pasting subtrees that reference a parent indentation you didn't copy; author forgetting the single top-level root node.

Related errors

AI-assisted analysis of mermaid-js/mermaid@d93e9c88c0 (2026-08-12). Data as JSON: /api/errors/1986b4e3ff6d5481. Report an issue: GitHub.