Nuxt Content Mermaid
中

Troubleshooting

Start with the symptom you can observe and reduce the application to the smallest failing diagram.

Install fails

Confirm:

  • Node.js is >=22.19.0.
  • Nuxt is ^4.1.0 and Nuxt Content is >=3.5.0 <4.0.0.
  • Your Nuxt Content database connector installed successfully.
  • If pnpm blocked a native connector's build script, review it and use pnpm approve-builds.

Next, align those versions and retry the unpinned installation command from Getting Started. Resolve database connector failures before debugging this module.

Build fails

Confirm:

  • @barzhsieh/nuxt-content-mermaid appears in the Nuxt modules array.
  • Options use contentMermaid, not the removed mermaidContent key.
  • enabled stays under the build-time contentMermaid option.
  • runtimeConfig.public.contentMermaid contains only serializable pure data.

Next, remove all package options and build with only the module registration. If that succeeds, restore options one group at a time and review Migration to v3 for changed boundaries.

Source stays visible

Confirm:

  • The Markdown fence language is exactly mermaid.
  • The route renders the intended Content page and JavaScript is enabled.
  • The browser console has no hydration, configuration, or Mermaid error.
  • The three-node example from Getting Started fails in the same way.

Next, test that reduced example on the direct Content route. If it renders, restore the original diagram incrementally and check its syntax with Mermaid's documentation. If it does not, capture the route, relevant configuration, build output, and browser error.

If the smallest example still fails, open a GitHub issue with the package, Nuxt, Nuxt Content, Node.js and package-manager versions, a minimal reproduction, and the complete error output.