mermaid-js/mermaid · error · Error

Commit positions not found for commits ${commitA.id} and ${c

Error message

Commit positions not found for commits ${commitA.id} and ${commitB.id}

What it means

Thrown by drawArrow in the gitGraph renderer when commitPos.get() returns undefined for either the source (commitA) or destination (commitB) commit. commitPos is a Map populated during the commit layout pass (drawCommits); an arrow references a commit id that was never positioned because it was never drawn or registered. This indicates a broken commit graph: a parent/child relationship points at a commit id the layout phase never processed.

Source

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

    lanes.push(candidate);
    return candidate;
  }
  const diff = Math.abs(y1 - y2);
  return findLane(y1, y2 - diff / 5, depth + 1);
};

const drawArrow = (
  svg: d3.Selection<SVGGElement, unknown, HTMLElement, any>,
  commitA: Commit,
  commitB: Commit,
  allCommits: Map<string, Commit>
) => {
  const { theme: arrowTheme } = getConfig();
  const useColorTheme = COLOR_THEMES.has(arrowTheme ?? '');
  const p1 = commitPos.get(commitA.id); // arrowStart
  const p2 = commitPos.get(commitB.id); // arrowEnd
  if (p1 === undefined || p2 === undefined) {
    throw new Error(`Commit positions not found for commits ${commitA.id} and ${commitB.id}`);
  }
  const arrowNeedsRerouting = shouldRerouteArrow(commitA, commitB, p1, p2, allCommits);
  // log.debug('drawArrow', p1, p2, arrowNeedsRerouting, commitA.id, commitB.id);

  // Lower-right quadrant logic; top-left is 0,0

  let arc = '';
  let arc2 = '';
  let radius = 0;
  let offset = 0;

  let colorClassNum = branchPos.get(commitB.branch)?.index;
  if (commitB.type === commitType.MERGE && commitA.id !== commitB.parents[0]) {
    colorClassNum = branchPos.get(commitA.branch)?.index;
  }

  let lineDef;
  if (arrowNeedsRerouting) {

View on GitHub (pinned to d93e9c88c0)

Solutions

Open the diagram source and verify every commit id referenced in branch/merge/commit lines is declared exactly once with a matching id.
Simplify the gitGraph to a linear history first, then re-add branches/merges one at a time to isolate the offending reference.
Check mermaid changelog for gitGraph grammar changes if this appeared after a version bump.
File an issue at the mermaid repo if the diagram is valid but still throws — include the minimal reproducing diagram text.

Example fix

// before
gitGraph
  commit id:"A"
  branch dev
  commit id:"B"
  merge maintypo   // typo: 'maintypo' is not a declared branch/commit

// after
gitGraph
  commit id:"A"
  branch dev
  commit id:"B"
  merge main        // correct branch name

Defensive patterns

Strategy: validation

Validate before calling

// Before rendering, verify every commit referenced in branches/merges exists.
// Pseudocode over the parsed gitGraph db:
const declared = new Set(db.getCommits().keys());
for (const [id, commit] of db.getCommits()) {
  for (const parentId of commit.parents ?? []) {
    if (!declared.has(parentId)) {
      throw new Error(`Commit ${id} references unknown parent ${parentId}`);
    }
  }
}

Type guard

function commitExists(db, id: string): id is string {
  return db.getCommits().has(id);
}

Try / catch

try {
  await mermaid.render('g', diagramText);
} catch (e) {
  if (e instanceof Error && /Commit positions not found/.test(e.message)) {
    // surface a user-facing message about a dangling commit reference
    showUserError('Your gitGraph references a commit that was never declared. Check commit ids in branch/merge lines.');
  } else {
    throw e;
  }
}

Prevention

Declare every commit with a unique explicit id before referencing it in branch/merge lines.
Use the mermaid Live Editor to validate gitGraph text before embedding it.
Add a CI step that runs mermaid.parse() on diagram sources to catch dangling references early.

When it happens

Trigger: Calling mermaid.render() on a gitGraph diagram where a commit is referenced as a parent (e.g. in a merge or branch statement) but was never declared with a commit statement; or a commit id typo makes the arrow target a non-existent id; or parallel-commits mode produces a commit that the layout loop skipped.

Common situations: Typo in commit ids between 'commit id:"A"' and 'merge A'; declaring branches/merges before the referenced commits exist; upgrading mermaid versions where the gitGraph grammar changed and a previously-valid diagram now leaves commits unprocessed; internal bugs in parallel commit layout.

Related errors

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