{"record":{"id":"1f3452b42910dc63","repo":"mermaid-js/mermaid","slug":"position-not-found-for-branch-branch-name","errorCode":null,"errorMessage":"Position not found for branch ${branch.name}","messagePattern":"Position not found for branch (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mermaid/src/diagrams/git/gitGraphRenderer.ts","lineNumber":887,"sourceCode":"  branches: { name: string }[],\n  gitGraphConfig: GitGraphDiagramConfig,\n  id: string\n) => {\n  const { look, theme, themeVariables } = getConfig();\n  const { dropShadow, THEME_COLOR_LIMIT: themeColorLimit } = themeVariables;\n  const useReduxGeometry = REDUX_GEOMETRY_THEMES.has(theme ?? '');\n  const useColorTheme = COLOR_THEMES.has(theme ?? '');\n  const g = svg.append('g');\n  branches.forEach((branch, index) => {\n    const adjustIndexForTheme = calcColorIndex(\n      index,\n      useReduxGeometry ? themeColorLimit : THEME_COLOR_LIMIT,\n      useColorTheme\n    );\n\n    const pos = branchPos.get(branch.name)?.pos;\n    if (pos === undefined) {\n      throw new Error(`Position not found for branch ${branch.name}`);\n    }\n    // LR spine Y: bkg rect center, dotted line, and commits all sit here.\n    // TB/BT use pos directly (their line attrs are overridden below).\n    const spineY =\n      dir === 'TB' || dir === 'BT'\n        ? pos\n        : useReduxGeometry\n          ? pos + REDUX_BRANCH_LABEL_PADDING_Y / 2 + 1\n          : pos - 2;\n    const line = g.append('line');\n    line.attr('x1', 0);\n    line.attr('y1', spineY);\n    line.attr('x2', maxPos);\n    line.attr('y2', spineY);\n    line.attr('class', 'branch branch' + adjustIndexForTheme);\n\n    if (dir === 'TB') {\n      line.attr('y1', defaultPos);","sourceCodeStart":869,"sourceCodeEnd":905,"githubUrl":"https://github.com/mermaid-js/mermaid/blob/d93e9c88c01a599c062ee6a3f1462e3558ac6b90/packages/mermaid/src/diagrams/git/gitGraphRenderer.ts#L869-L905","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If using mermaid programmatically, ensure you run the full parse + db setup before invoking the renderer — use mermaid.render() rather than calling drawBranches directly.","Verify the gitGraph text declares branches with the standard 'branch <name>' syntax and that names contain no stray whitespace.","Report upstream with the diagram text if input is valid standard syntax — this guard is meant to be unreachable for well-formed input.","Upgrade mermaid; branch registration fixes land regularly."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":"function branchHasPosition(branchPos: Map<string, {pos?: number}>, name: string): boolean {\n  return branchPos.get(name)?.pos !== undefined;\n}","tryCatchPattern":"try {\n  await mermaid.render('g', diagramText);\n} catch (e) {\n  if (e instanceof Error && /Position not found for branch/.test(e.message)) {\n    showUserError('A branch in your gitGraph could not be positioned. Ensure branches are declared with standard syntax.');\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always go through the full mermaid.render() pipeline rather than calling internal draw functions directly.","Declare branches with 'branch <name>' before referencing them.","Report unreachable-for-valid-input throws upstream."],"tags":["mermaid","gitgraph","rendering","internal-invariant"],"backgroundTag":null,"analyzedSha":"d93e9c88c01a599c062ee6a3f1462e3558ac6b90","analyzedAt":"2026-08-12T06:23:11.304Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}