mermaid-js/mermaid · error · Error

Position not found for branch ${branch.name}

Error message

Position not found for branch ${branch.name}

What it means

Thrown while drawing branch spines in drawBranches when branchPos.get(branch.name) has no .pos value. branchPos is populated during the db parse/processing phase; if the branches array contains a branch name that was never registered in branchPos, the spine cannot be placed and the renderer aborts. This signals a mismatch between the branches list and the position map — typically an internal wiring or parse-order bug rather than a user syntax error.

Source

Thrown at packages/mermaid/src/diagrams/git/gitGraphRenderer.ts:887

  branches: { name: string }[],
  gitGraphConfig: GitGraphDiagramConfig,
  id: string
) => {
  const { look, theme, themeVariables } = getConfig();
  const { dropShadow, THEME_COLOR_LIMIT: themeColorLimit } = themeVariables;
  const useReduxGeometry = REDUX_GEOMETRY_THEMES.has(theme ?? '');
  const useColorTheme = COLOR_THEMES.has(theme ?? '');
  const g = svg.append('g');
  branches.forEach((branch, index) => {
    const adjustIndexForTheme = calcColorIndex(
      index,
      useReduxGeometry ? themeColorLimit : THEME_COLOR_LIMIT,
      useColorTheme
    );

    const pos = branchPos.get(branch.name)?.pos;
    if (pos === undefined) {
      throw new Error(`Position not found for branch ${branch.name}`);
    }
    // LR spine Y: bkg rect center, dotted line, and commits all sit here.
    // TB/BT use pos directly (their line attrs are overridden below).
    const spineY =
      dir === 'TB' || dir === 'BT'
        ? pos
        : useReduxGeometry
          ? pos + REDUX_BRANCH_LABEL_PADDING_Y / 2 + 1
          : pos - 2;
    const line = g.append('line');
    line.attr('x1', 0);
    line.attr('y1', spineY);
    line.attr('x2', maxPos);
    line.attr('y2', spineY);
    line.attr('class', 'branch branch' + adjustIndexForTheme);

    if (dir === 'TB') {
      line.attr('y1', defaultPos);

View on GitHub (pinned to d93e9c88c0)

Solutions

1. If using mermaid programmatically, ensure you run the full parse + db setup before invoking the renderer — use mermaid.render() rather than calling drawBranches directly.
2. Verify the gitGraph text declares branches with the standard 'branch <name>' syntax and that names contain no stray whitespace.
3. Report upstream with the diagram text if input is valid standard syntax — this guard is meant to be unreachable for well-formed input.
4. Upgrade mermaid; branch registration fixes land regularly.

function branchHasPosition(branchPos: Map<string, {pos?: number}>, name: string): boolean {
  return branchPos.get(name)?.pos !== undefined;
}

try {
  await mermaid.render('g', diagramText);
} catch (e) {
  if (e instanceof Error && /Position not found for branch/.test(e.message)) {
    showUserError('A branch in your gitGraph could not be positioned. Ensure branches are declared with standard syntax.');
  } else {
    throw e;
  }
}

When it happens

Trigger: A branch object exists in the branches array (iterated by forEach) but branchPos was never keyed with its name; calling draw before the db's branch-registration phase ran; a custom diagram integration that mutates the branches array without updating branchPos.

Common situations: Happens with malformed gitGraph input that registers a branch name through an unusual grammar path; after refactoring mermaid internals where branch registration order changed; in programmatic use where someone calls the renderer directly without the full parse→db→draw pipeline.

Related errors

• Line definition not found
• Commit positions not found for commits ${commitA.id} and ${c
• Groups within groups are not allowed in Kanban diagrams
• start should have been set during first phase
• end should have been set during first phase

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