Skip to main content

Troubleshooting Mermaid Plugin Integration

This guide addresses specific issues that may arise when integrating the Mermaid.js plugin into Docusaurus and how to resolve the resulting 502 Bad Gateway errors.

1. Stale DNS Cache in Cloudflare Tunnel​

The Problem​

After installing the Mermaid plugin (or any package) and restarting the Docusaurus container, the Cloudflare Tunnel may still try to connect to the old container's IP address. This results in a "Connection Refused" error in the tunnel logs and a 502 error in the browser, even if Docusaurus is healthy.

How to Diagnose​

Check the cloudflared logs:

sudo docker logs cloudflared | grep "connection refused"

If you see entries like dial tcp 172.20.0.X:3000: connect: connection refused, it means the tunnel is tracking a stale IP.

The Solution​

Restart the Cloudflare Tunnel container to refresh its DNS resolution and connection pool:

sudo docker restart cloudflared

2. Increased Build Time & Startup Lag​

The Problem​

Mermaid.js adds significant overhead to the Docusaurus build process (Webpack/Babel compilation). This means that after a restart, the "Startup Lag" is longer than usual, often extending the 502 error window to several minutes.

The Solution​

Be patient. Monitor the build progress live to know exactly when the site is ready:

sudo docker logs -f docusaurus

Wait for the line: [SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/.

3. Configuration Errors in docusaurus.config.js​

The Problem​

Incorrectly adding Mermaid to the configuration can cause the build to fail immediately.

Correct Configuration​

Ensure your docusaurus.config.js includes both the markdown setting AND the theme:

module.exports = {
  // ...
  markdown: {
    mermaid: true, // Required for Mermaid support
  },
  themes: ['@docusaurus/theme-mermaid'], // Required for the Mermaid theme
  // ...
};

Verification​

If the build fails, look for Error: Cannot find module '@docusaurus/theme-mermaid' in the logs. If you see this, run:

sudo docker exec docusaurus npm install @docusaurus/theme-mermaid
sudo docker restart docusaurus

Summary Checklist​

  • Restart cloudflared to clear stale connections.
  • Monitor docker logs -f docusaurus and wait for the "Serving" success message.
  • Verify that @docusaurus/theme-mermaid is in package.json and docusaurus.config.js.