fix: prevent undefined shape error in flowchart syntax parsing

[darshanr0107]

📑 Summary

Fixes a flowchart runtime error where Mermaid attempted to access the shape property on an undefined node, causing the renderer to crash.
Resolves #6662

📏 Design Decisions

Describe the way your implementation works or what design decisions you made if applicable.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4a953e0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	4a953e0
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a01f667e79f8600081b068c
😎 Deploy Preview	https://deploy-preview-7314--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7314

mermaid

npm i https://pkg.pr.new/mermaid@7314

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7314

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7314

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7314

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7314

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7314

commit: 4a953e0

[codecov]

Codecov Report

❌ Patch coverage is 0% with 48 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.27%. Comparing base (2f4e702) to head (4a953e0).

Files with missing lines	Patch %	Lines
...g-util/layout-algorithms/dagre/mermaid-graphlib.js	0.00%	48 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7314      +/-   ##
==========================================
- Coverage     3.27%   3.27%   -0.01%     
==========================================
  Files          598     597       -1     
  Lines        60420   60457      +37     
  Branches       913     913              
==========================================
  Hits          1980    1980              
- Misses       58440   58477      +37     

Flag	Coverage Δ
unit	3.27% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...g-util/layout-algorithms/dagre/mermaid-graphlib.js	0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	1 added	May 11, 2026, 3:49 PM

[knsv-bot]

[sisyphus-bot]

Thanks for picking up #6662 — this is a tricky one. The crash happens because adjustClustersAndEdges picks an anchor node that lives inside a sibling extractable subgraph, and when that subgraph gets collapsed into a clusterNode the original anchor disappears. The new helpers correctly identify a safer alternative for the canonical failing case. A few things below before this is ready to land.

What's working well

• 🎉 [praise] Clear separation of concerns: isNodeInExtractableCluster is a small pure predicate, findSafeAnchorNode is a focused selection helper, both with JSDoc. Keeping them unexported is the right call — they're internals.
• 🎉 [praise] End-to-end test (flowchart-v2.spec.js:1214) uses the exact failing diagram from the linked issue (extended with a couple of extra nodes for snapshot stability). Argos will catch any regressions in the cluster-edge anchoring of unrelated diagrams that go through adjustClustersAndEdges.

Things to address

• 🟡 [important] mermaid-graphlib.js:253 — isNodeInExtractableCluster(graph, nonClusterChild, id); is called but its return value is discarded. The comment immediately above says "Check if the current anchor is invalid," which suggests the original intent was:

  if (isNodeInExtractableCluster(graph, nonClusterChild, id)) {
    const safeAnchor = findSafeAnchorNode(graph, id, graph.parent(nonClusterChild));
    if (safeAnchor) {
      clusterDb.get(id).id = safeAnchor;
    }
  }

  As written, findSafeAnchorNode runs for every cluster with externalConnections && hasDirectOutgoingEdge — including ones whose current anchor is already perfectly valid. That's a much broader set than the bug scenario (any flowchart with a cluster-->node style edge enters this branch). If findSafeAnchorNode returns a different-but-also-valid node, the cluster's anchor changes, which may shift edge attachment points on diagrams that previously rendered fine. Could you either (a) reinstate the guard so the change only fires when the existing anchor is genuinely broken, or (b) remove the dead call and document why running it unconditionally is intentional? Either way the current state reads like leftover-from-refactor and is hard to reason about.

Nits

• 🟢 [nit] mermaid-graphlib.js:445 — findSafeAnchorNode skips leaf children via if (!candidate || candidate === child) continue. Because findNonClusterChild(leaf, graph, ...) returns the leaf itself, the candidate === child branch always fires for leaves. That means a topology like cluster with one extractable nested subgraph (containing the bad anchor) plus one leaf sibling at the same level would have findSafeAnchorNode return null and fall back to the broken anchor — even though the leaf sibling would be a perfectly valid replacement. Probably not common, but worth a follow-up test case to confirm whether this edge case still crashes.

• 🟢 [nit] flowchart-v2.spec.js:1244 — the test passes { htmlLabels: true, flowchart: { htmlLabels: true }, securityLevel: 'loose' }. None of those are needed to reproduce the crash (the diagram has only plain identifiers). Stripping them down to {} would isolate the fix and make the test's intent clearer. Not blocking — securityLevel: 'loose' is used elsewhere in the file as well.

Security

XSS review confirms no new DOM sinks, no DOMPurify/sanitization changes, and the new helpers operate purely on graphlib's abstract topology. The test diagram contains only alphanumeric identifiers. No security concerns.

Self-check

Severity	Count
🔴 blocking	0
🟡 important	1
🟢 nit	2
💡 suggestion	0
🎉 praise	2

Verdict: COMMENT. The fix solves the reported crash and is structurally clean — the dead call at line 253 is the only thing that genuinely needs resolving before merge. Looking forward to seeing this one across the line. 🙌

[knsv-bot]

Pushed 4a953e0d5 — merge of latest develop plus the review-feedback fixes.

Conflict resolution

cypress/integration/rendering/flowchart-v2.spec.js had a conflict because develop moved the file into a flowchart/ subdirectory and appended an Edge label autowrapping describe block. Kept both — V2-18 plus the autowrap block — at the file's new location.

Review feedback applied

• 🟡 Dead isNodeInExtractableCluster call — guarded the safe-anchor re-mapping with the predicate so the change only fires when the current anchor would genuinely be lost to subgraph extraction. The previous unconditional call meant any flowchart with cluster-->node style edges entered the re-anchoring path, even when the existing anchor was fine.

• 🟢 Leaf-sibling edge case in findSafeAnchorNode — dropped the candidate === child skip so a leaf sibling at the cluster level can be returned. findNonClusterChild returns the leaf's id when called on a leaf; that's a legitimate anchor, not a "no result" sentinel.

• 🟢 Test config — simplified to {} since the failing diagram has only plain identifiers; htmlLabels/securityLevel: loose were vestigial.

Verification

• npx tsc --noEmit -p packages/mermaid/tsconfig.json → 0 errors.
• npx vitest run packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.spec.js → 15/15 pass.
• Pre-commit hook (eslint + prettier + docs:build + types:build-config) passed.

The Cypress test will re-run on the new commit and Argos will surface any visual deltas on diagrams whose anchor selection now changes.

[knsv-bot]

Confirming all three items from the review are addressed in 4a953e0d5:

🟡 Dead isNodeInExtractableCluster call — mermaid-graphlib.js:251-260
isNodeInExtractableCluster(...) is now the fourth predicate of the guarding if:

```js
if (
nonClusterChild &&
clusterDb.get(id)?.externalConnections &&
hasDirectOutgoingEdge &&
isNodeInExtractableCluster(graph, nonClusterChild, id)
) {
const safeAnchor = findSafeAnchorNode(graph, id, graph.parent(nonClusterChild));
if (safeAnchor) {
clusterDb.get(id).id = safeAnchor;
}
}
```

Re-anchoring only fires when the current anchor is genuinely inside an extractable cluster. The standalone call is gone.

🟢 Leaf-sibling skip in findSafeAnchorNode — mermaid-graphlib.js:455-458
Replaced if (!candidate || candidate === child) with if (!candidate). findNonClusterChild returns the leaf id for leaf children — that's a valid anchor, not a "no result" sentinel. Comment added explaining the rationale.

🟢 Test config simplified — cypress/integration/rendering/flowchart/flowchart-v2.spec.js:1320
V2-18 now passes {} instead of { htmlLabels: true, flowchart: { htmlLabels: true }, securityLevel: 'loose' }. Test intent is now isolated to the cluster-anchor regression.

CI / Argos will surface any visual deltas on diagrams whose anchor selection changes under the tighter guard.

[knsv-bot]

[sisyphus-bot]

Follow-up review on 4a953e0d5. All three items from the previous round are resolved cleanly. Nothing else to flag.

What's working well

• 🎉 [praise] The dead isNodeInExtractableCluster call is gone — it's now the fourth predicate in the guarding if (...). Re-anchoring fires only when the current anchor is genuinely sitting inside an extractable cluster, which keeps the change scoped to the actual bug shape rather than every cluster with a direct outgoing edge. The leading comment explaining why the re-anchor exists is a nice touch.

• 🎉 [praise] findSafeAnchorNode now accepts leaf siblings — if (!candidate) continue instead of if (!candidate || candidate === child) continue. The added comment ("findNonClusterChild returns the leaf itself when child is a leaf… A returned leaf sibling is a perfectly valid anchor") preempts the exact confusion the original code created. This unblocks the edge case I worried about: a cluster whose only safe-anchor option is a leaf sibling at the same level.

• 🎉 [praise] V2-18 test is now {}. Stripped-down test config makes the regression's intent obvious — "this diagram must not crash" — and removes the noise of unrelated config flags.

Security

No additional security review needed — the changes since the previous round only tighten the predicate guard. No new sinks, no DOMPurify changes. The pure-graph-topology character of the helpers is unchanged.

Self-check

Severity	Count
🔴 blocking	0
🟡 important	0
🟢 nit	0
💡 suggestion	0
🎉 praise	3

Verdict: APPROVE. All review items resolved, scope is tight, the bug-fix logic is now bounded to the actual broken-anchor case. Argos will surface any visual deltas on diagrams whose anchor changes under the new guard — happy to see those approved and merged. 🙌