Error handling and debugging

Overview

Mermaid provides comprehensive error handling mechanisms to help you identify and resolve issues with diagram syntax, rendering, and configuration. This guide covers error detection, handling strategies, and debugging techniques.

Error types

UnknownDiagramError

Thrown when Mermaid cannot detect the diagram type (errors.ts:1):

export class UnknownDiagramError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'UnknownDiagramError';
  }
}

This error occurs when the diagram text doesn’t match any registered diagram detector:

try {
  const type = mermaid.detectType('invalid diagram text');
} catch (error) {
  if (error instanceof UnknownDiagramError) {
    console.error('Unknown diagram type:', error.message);
  }
}

Parse errors

Parse errors occur when diagram syntax is invalid. These are caught during the parsing phase.

Render errors

Render errors happen during diagram rendering and may be caused by configuration issues or browser limitations.

The parse function

Use mermaid.parse() to validate diagram syntax without rendering (mermaidAPI.ts:67):

async function parse(
  text: string,
  parseOptions?: ParseOptions
): Promise<ParseResult | false>

Basic validation

// Validate and get diagram type
try {
  const result = await mermaid.parse('flowchart TD\nA-->B');
  console.log(result); // { diagramType: 'flowchart' }
} catch (error) {
  console.error('Invalid syntax:', error);
}

Suppressing errors

Use suppressErrors: true to return false instead of throwing:

const isValid = await mermaid.parse('wrong syntax', { suppressErrors: true });
if (isValid) {
  console.log('Valid diagram:', isValid.diagramType);
} else {
  console.log('Invalid diagram');
}

Examples from source

From mermaid.ts:336:

/**
 * @example
 * ```js
 * console.log(await mermaid.parse('flowchart \n a --> b'));
 * // { diagramType: 'flowchart-v2' }
 * console.log(await mermaid.parse('wrong \n a --> b', { suppressErrors: true }));
 * // false
 * console.log(await mermaid.parse('wrong \n a --> b', { suppressErrors: false }));
 * // throws Error
 * console.log(await mermaid.parse('wrong \n a --> b'));
 * // throws Error
 * ```
 */

Error handling in render

The render function provides built-in error handling (mermaidAPI.ts:392):

let diag: Diagram;
let parseEncounteredException;

try {
  diag = await Diagram.fromText(text, { title: processed.title });
} catch (error) {
  if (config.suppressErrorRendering) {
    removeTempElements();
    throw error;
  }
  diag = await Diagram.fromText('error');
  parseEncounteredException = error;
}

// ... render the diagram ...

try {
  await diag.renderer.draw(text, id, injected.version, diag);
} catch (e) {
  if (config.suppressErrorRendering) {
    removeTempElements();
  } else {
    errorRenderer.draw(text, id, injected.version);
  }
  throw e;
}

if (parseEncounteredException) {
  throw parseEncounteredException;
}

Suppress error rendering

Control whether error diagrams are displayed:

mermaid.initialize({
  suppressErrorRendering: true  // Don't show error diagram, just throw
});

try {
  await mermaid.render('id', 'invalid syntax');
} catch (error) {
  // Handle error yourself
  console.error('Render failed:', error);
  document.getElementById('errorDisplay').textContent = error.message;
}

Custom error handlers

Setting a parse error handler

Set a global error handler for parse errors (mermaid.ts:304):

mermaid.parseError = function (err, hash) {
  // Custom error handling
  console.error('Parse error:', err);
  displayErrorInGui(err);
};

// Or use the helper function
mermaid.setParseErrorHandler(function (err, hash) {
  console.error('Parse error:', err, hash);
});

DetailedError interface

Mermaid provides detailed error information:

interface DetailedError {
  str: string;        // Error message
  message: string;    // Error message (duplicate for compatibility)
  hash: string;       // Error identifier/type
  error: Error;       // Original error object
}

Error handling in run()

The run() function handles errors from multiple diagrams (mermaid.ts:64):

const handleError = (error: unknown, errors: DetailedError[], parseError?: ParseErrorFunction) => {
  log.warn(error);
  if (isDetailedError(error)) {
    if (parseError) {
      parseError(error.str, error.hash);
    }
    errors.push({ ...error, message: error.str, error });
  } else {
    if (parseError) {
      parseError(error);
    }
    if (error instanceof Error) {
      errors.push({
        str: error.message,
        message: error.message,
        hash: error.name,
        error,
      });
    }
  }
};

Using suppressErrors in run()

When rendering multiple diagrams with mermaid.run(), suppress errors to continue processing:

await mermaid.run({
  querySelector: '.mermaid',
  suppressErrors: true  // Don't throw on first error
});

From mermaid.ts:109:

const run = async function (options: RunOptions = { querySelector: '.mermaid' }) {
  try {
    await runThrowsErrors(options);
  } catch (e) {
    if (isDetailedError(e)) {
      log.error(e.str);
    }
    if (mermaid.parseError) {
      mermaid.parseError(e as string);
    }
    if (!options.suppressErrors) {
      log.error('Use the suppressErrors option to suppress these errors');
      throw e;
    }
  }
};

Debugging techniques

Enable debug logging

mermaid.initialize({
  logLevel: 'debug'
});

Log levels: 'fatal', 'error', 'warn', 'info', 'debug', 'trace'

Check diagram type detection

Verify which diagram type Mermaid detects:

import mermaid from 'mermaid';

const definition = `sequenceDiagram
  Alice->>Bob: Hello`;

try {
  const type = mermaid.detectType(definition);
  console.log('Detected type:', type); // 'sequence'
} catch (error) {
  console.error('Detection failed:', error);
}

Validate before rendering

Parse the diagram

const text = document.getElementById('diagram-input').value;
const parseResult = await mermaid.parse(text, { suppressErrors: true });

Check validation result

if (!parseResult) {
  console.error('Invalid diagram syntax');
  showError('Please check your diagram syntax');
  return;
}

console.log('Valid diagram type:', parseResult.diagramType);

Render the diagram

try {
  const { svg, bindFunctions } = await mermaid.render('diagram-id', text);
  document.getElementById('output').innerHTML = svg;
  bindFunctions?.(document.getElementById('output'));
} catch (error) {
  console.error('Render failed:', error);
  showError('Failed to render diagram');
}

Common errors and solutions

Text size exceeded

Error: Maximum text size in diagram exceeded Cause: Diagram text exceeds maxTextSize limit (default: 50,000 characters) Solution:

mermaid.initialize({
  maxTextSize: 100000  // Increase limit
});

Large diagrams may cause performance issues. Consider breaking them into smaller diagrams.

Unknown diagram type

Error: UnknownDiagramError: No diagram type detected Cause: The diagram syntax doesn’t match any registered diagram type Solutions:

Check the diagram keyword (e.g., flowchart, sequenceDiagram)
Ensure the diagram type is registered
Remove comments and directives that may interfere with detection

// Bad
flowchar TD  // Typo
A-->B

// Good
flowchart TD
A-->B

Parse errors with directives

Error: Parse fails with %%init%% directive Cause: Directive syntax is incorrect Solution:

// Bad
%%init: { "theme": "dark" }%%

// Good
%%{init: {"theme": "dark"}}%%
flowchart TD
A-->B

Error recovery patterns

Graceful degradation

const renderDiagram = async (text, containerId) => {
  const container = document.getElementById(containerId);
  
  try {
    // Try to parse first
    const parseResult = await mermaid.parse(text);
    console.log('Valid diagram:', parseResult.diagramType);
    
    // Render
    const { svg, bindFunctions } = await mermaid.render(containerId, text);
    container.innerHTML = svg;
    bindFunctions?.(container);
    
    return { success: true };
  } catch (error) {
    // Show error message instead of diagram
    container.innerHTML = `
      <div style="color: red; border: 1px solid red; padding: 10px;">
        <strong>Error rendering diagram:</strong><br>
        ${error.message}
      </div>
    `;
    
    // Log for debugging
    console.error('Render error:', error);
    
    return { success: false, error };
  }
};

Retry with fallback

const renderWithFallback = async (text, containerId) => {
  try {
    // Try primary rendering
    return await mermaid.render(containerId, text);
  } catch (error) {
    console.warn('Primary render failed, trying fallback:', error);
    
    // Try with stricter security
    const originalConfig = mermaid.getConfig();
    mermaid.initialize({
      ...originalConfig,
      securityLevel: 'strict',
      suppressErrorRendering: false
    });
    
    try {
      return await mermaid.render(containerId, text);
    } finally {
      // Restore original config
      mermaid.initialize(originalConfig);
    }
  }
};

User-friendly error messages

const ERROR_MESSAGES = {
  UnknownDiagramError: 'The diagram type is not recognized. Please check the first line of your diagram.',
  ParseError: 'There is a syntax error in your diagram. Please check the syntax.',
  RenderError: 'Failed to render the diagram. This may be a browser compatibility issue.',
};

const getUserFriendlyError = (error) => {
  if (error instanceof UnknownDiagramError) {
    return ERROR_MESSAGES.UnknownDiagramError;
  }
  if (error.name === 'ParseError') {
    return ERROR_MESSAGES.ParseError;
  }
  return ERROR_MESSAGES.RenderError;
};

try {
  await mermaid.render('id', text);
} catch (error) {
  const userMessage = getUserFriendlyError(error);
  alert(userMessage);
  console.error('Technical details:', error);
}

Testing and validation

Automated validation

const validateDiagrams = async (diagrams) => {
  const results = [];
  
  for (const { name, text } of diagrams) {
    const result = await mermaid.parse(text, { suppressErrors: true });
    
    results.push({
      name,
      valid: !!result,
      diagramType: result ? result.diagramType : null
    });
  }
  
  return results;
};

// Usage
const diagrams = [
  { name: 'Flow 1', text: 'flowchart TD\nA-->B' },
  { name: 'Sequence 1', text: 'sequenceDiagram\nA->>B:Hello' },
  { name: 'Invalid', text: 'invalid diagram' }
];

const results = await validateDiagrams(diagrams);
console.table(results);

Logging and monitoring

Custom logger

import { setLogLevel, log } from 'mermaid';

// Set log level
setLogLevel('debug');

// Use built-in logger
log.debug('Debug message');
log.info('Info message');
log.warn('Warning message');
log.error('Error message');

Error tracking integration

import * as Sentry from '@sentry/browser';

mermaid.parseError = function (err, hash) {
  // Log to console
  console.error('Mermaid parse error:', err);
  
  // Send to error tracking
  Sentry.captureException(err, {
    tags: {
      component: 'mermaid',
      errorType: 'parse',
      hash: hash
    }
  });
};

const renderWithTracking = async (text, id) => {
  try {
    return await mermaid.render(id, text);
  } catch (error) {
    Sentry.captureException(error, {
      tags: {
        component: 'mermaid',
        errorType: 'render'
      },
      extra: {
        diagramText: text,
        diagramId: id
      }
    });
    throw error;
  }
};

Getting Started

Core Concepts

Diagram Types

Configuration

Advanced

Error handling and debugging

Overview

Error types

UnknownDiagramError

Parse errors

Render errors

The parse function

Basic validation

Suppressing errors

Examples from source

Error handling in render

Suppress error rendering

Custom error handlers

Setting a parse error handler

DetailedError interface

Error handling in run()

Using suppressErrors in run()

Debugging techniques

Enable debug logging

Check diagram type detection

Validate before rendering

Common errors and solutions

Text size exceeded

Unknown diagram type

Parse errors with directives

Error recovery patterns

Graceful degradation

Retry with fallback

User-friendly error messages

Testing and validation

Automated validation

Logging and monitoring

Custom logger

Error tracking integration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Diagram Types

Configuration

Advanced

​Overview

​Error types

​UnknownDiagramError

​Parse errors

​Render errors

​The parse function

​Basic validation

​Suppressing errors

​Examples from source

​Error handling in render

​Suppress error rendering

​Custom error handlers

​Setting a parse error handler

​DetailedError interface

​Error handling in run()

​Using suppressErrors in run()

​Debugging techniques

​Enable debug logging

​Check diagram type detection

​Validate before rendering

​Common errors and solutions

​Text size exceeded

​Unknown diagram type

​Parse errors with directives

​Error recovery patterns

​Graceful degradation

​Retry with fallback

​User-friendly error messages

​Testing and validation

​Automated validation

​Logging and monitoring

​Custom logger

​Error tracking integration

​Related topics

Build docs developers (and LLMs) love

Overview

Error types

UnknownDiagramError

Parse errors

Render errors

The parse function

Basic validation

Suppressing errors

Examples from source

Error handling in render

Suppress error rendering

Custom error handlers

Setting a parse error handler

DetailedError interface

Error handling in run()

Using suppressErrors in run()

Debugging techniques

Enable debug logging

Check diagram type detection

Validate before rendering

Common errors and solutions

Text size exceeded

Unknown diagram type

Parse errors with directives

Error recovery patterns

Graceful degradation

Retry with fallback

User-friendly error messages

Testing and validation

Automated validation

Logging and monitoring

Custom logger

Error tracking integration

Related topics