mermaid-js/mermaid · error

Diagrams beginning with --- are not valid. If you were tryin

Error message

Diagrams beginning with --- are not valid. If you were trying to use a YAML front-matter, please ensure that you've correctly opened and closed the YAML front-matter with un-indented `---` blocks

What it means

Thrown by a special stub diagram registered in diagram-orchestration for any text that starts (after lowercasing/trimming) with '---'. The stub's parse() always throws, because a bare '---' opener is treated as a malformed YAML front-matter block rather than a real diagram. It only parses if you also close the front matter correctly.

Source

Thrown at packages/mermaid/src/diagram-api/diagram-orchestration.ts:72

  });
  registerDiagram(
    '---',
    // --- diagram type may appear if YAML front-matter is not parsed correctly
    {
      db: {
        clear: () => {
          // Quite ok, clear needs to be there for --- to work as a regular diagram
        },
      },
      styles: {}, // should never be used
      renderer: {
        draw: () => {
          // should never be used
        },
      },
      parser: {
        parse: () => {
          throw new Error(
            'Diagrams beginning with --- are not valid. ' +
              'If you were trying to use a YAML front-matter, please ensure that ' +
              "you've correctly opened and closed the YAML front-matter with un-indented `---` blocks"
          );
        },
      },
      init: () => null, // no op
    },
    (text) => {
      return text.toLowerCase().trimStart().startsWith('---');
    }
  );

  if (injected.includeLargeFeatures) {
    registerLazyLoadedDiagrams(flowchartElk, mindmap, architecture);
  }

  // Ordering of detectors is important. The first one to return true will be used.

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Wrap front matter in a matching pair of un-indented '---' lines and put the diagram after the closing one.
2. Remove the leading '---' if no front matter was intended.
3. Ensure the opening '---' is not indented; indented '---' is not recognised as front matter.

Example fix

// before
---
title: My Diagram
graph TD; A-->B

// after
---
title: My Diagram
---
graph TD; A-->B

function hasClosedFrontMatter(text: string): boolean {
  const t = text.trimStart();
  if (!t.startsWith('---')) return true;
  const after = t.slice(3);
  return /(^|\n)---(\s|$)/.test(after);
}
if (!hasClosedFrontMatter(text)) {
  throw new Error('Unclosed YAML front matter');
}

try {
  await Diagram.fromText(text);
} catch (e) {
  if (e instanceof Error && e.message.includes('Diagrams beginning with ---')) {
    // prompt user to fix/remove front matter
  } else throw e;
}

When it happens

Trigger: Diagram text begins with '---' but the front matter is never closed with a second '---', or the text is literally just '---' with no diagram body after it.

Common situations: A user pastes a markdown file whose leading '---' front matter was left in, or hand-writes a diagram and accidentally starts it with '---'.

Related errors

• Diagram ${type} not found.
• No diagram type detected matching given configuration for te
• Diagram ${name} not found.
• Failed to load ${failed.length} external diagrams
• The service id [${id}] is already in use by another ${this.r

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