danny-avila/LibreChat · warning · Error

Invalid mermaid syntax

Error message

Invalid mermaid syntax

What it means

Thrown when `mermaidInstance.parse(content)` rejects — i.e. the diagram source text is not valid Mermaid syntax. The hook extracts a readable message from the parse error (using `parseError.message` if it's an Error, else the string) and re-throws with that message, so the surfaced text is Mermaid's own diagnostic rather than the generic `'Invalid mermaid syntax'` default (which only appears when the error is neither an Error nor a string).

Source

Thrown at client/src/hooks/Mermaid/useMermaid.ts:131

      const mermaidInstance = await loadMermaid();

      if (!mermaidInstance) {
        throw new Error('Failed to load mermaid library');
      }

      // Validate syntax first and capture detailed error
      try {
        await mermaidInstance.parse(content);
      } catch (parseError) {
        // Extract meaningful error message from mermaid's parse error
        let errorMessage = 'Invalid mermaid syntax';
        if (parseError instanceof Error) {
          errorMessage = parseError.message;
        } else if (typeof parseError === 'string') {
          errorMessage = parseError;
        }

        throw new Error(errorMessage);
      }

      // Initialize with config
      mermaidInstance.initialize(mermaidConfig);

      // Render to SVG
      const { svg } = await mermaidInstance.render(diagramId, content);

      const sanitizedSvg = sanitizeMermaidSvg(svg);

      // Store as last valid content
      setValidContent(sanitizedSvg);

      return sanitizedSvg;
    } catch (error) {
      console.error('Mermaid rendering error:', error);

      // Return last valid content if available (graceful degradation)

View on GitHub (pinned to 5ff282f900)

Solutions

1. Read the exact message Mermaid attached to the parse error — it typically names the offending line/token.
2. Paste the diagram into the Mermaid Live Editor to get an interactive parse diagnostic and a corrected version.
3. If the error appeared after a Mermaid version bump, check the upgrade guide for breaking syntax changes and update affected diagrams.
4. Sanitize user/AI input (strip smart quotes, non-breaking spaces) before parsing.

Example fix

// before — generic fallback masks the real error
let errorMessage = 'Invalid mermaid syntax';
if (parseError instanceof Error) errorMessage = parseError.message;
// after — surface the line context Mermaid provides when available
let errorMessage = 'Invalid mermaid syntax';
if (parseError instanceof Error) {
  errorMessage = parseError.message;
} else if (parseError?.str !== undefined) { // mermaid Diagnostic carries .str
  errorMessage = parseError.str;
}

// Pre-validate syntax with a lighter check before full parse (optional)
if (typeof content !== 'string' || content.trim().length === 0) {
  throw new Error('Empty Mermaid diagram');
}

function isNonEmptyMermaidSource(s: unknown): s is string {
  return typeof s === 'string' && s.trim().length > 0;
}

try {
  await mermaidInstance.parse(content);
} catch (parseError) {
  const msg = parseError instanceof Error ? parseError.message : String(parseError);
  setErrorMessage(msg); // show Mermaid's diagnostic to the user
}

When it happens

Trigger: A user-authored or AI-generated Mermaid code block contains a syntax error: undeclared diagram type, mismatched brackets, invalid node shapes, unsupported directives, or a Mermaid version that doesn't understand newer syntax. The render hook calls `parse` before `render` so the failure is caught before canvas/SVG generation.

Common situations: LLM-generated Mermaid that uses non-existent directives or wrong keywords; a Mermaid library upgrade that changed syntax (e.g. v9 → v10 breaking changes); copy-pasted diagrams with smart quotes or invisible characters; user-typed diagrams with typos in keywords like `graph`/`flowchart`/`sequenceDiagram`.

Related errors

• Failed to load mermaid library
• [${req.baseUrl}] Endpoint is required
• Text is required
• Error uploading file: ${result.message}
• Unexpected batch upload response: ${JSON.stringify(result).s

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/098f85c474f93a38. Report an issue: GitHub.