# How to Use the Docusaurus Debug Plugin to Diagnose Build Issues

> Troubleshoot Docusaurus build issues with the debug plugin. Inspect configuration, routes, content, and global data at __docusaurus/debug for faster problem-solving.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**The Docusaurus debug plugin (`@docusaurus/plugin-debug`) exposes a debugging UI at `/__docusaurus/debug` that lets you inspect configuration, routes, content, and global data to troubleshoot build problems.**

When static site generation fails or routes behave unexpectedly in the **facebook/docusaurus** repository, the **Docusaurus debug plugin** provides a built-in diagnostic interface. This official plugin renders a React-based debugging UI that exposes the internal state of your site, making it invaluable for plugin authors and developers tracing build-time issues.

## What the Docusaurus Debug Plugin Exposes

The plugin registers routes under `/__docusaurus/debug` that render a navigation layout defined in [[`packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx). This `DebugLayout` component provides access to six diagnostic pages:

- **`/__docusaurus/debug`** – Displays the **Config** page (`DebugConfig`) showing your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) values as rendered by [[`DebugConfig/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugConfig/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.tsx).
- **`/__docusaurus/debug/metadata`** – Shows site-wide **metadata** via `DebugSiteMetadata` in [[`DebugSiteMetadata/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugSiteMetadata/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugSiteMetadata/index.tsx).
- **`/__docusaurus/debug/registry`** – Lists the **component registry** (`DebugRegistry`) as implemented in [[`DebugRegistry/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugRegistry/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugRegistry/index.tsx).
- **`/__docusaurus/debug/routes`** – Enumerates all **router routes** (`DebugRoutes`) generated during the build, rendered by [[`DebugRoutes/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugRoutes/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugRoutes/index.tsx).
- **`/__docusaurus/debug/content`** – Renders the full **content model** (`DebugContent`) including processed Markdown/MDX and sidebar data via [[`DebugContent/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugContent/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx).
- **`/__docusaurus/debug/globalData`** – Displays the **global data** object (`DebugGlobalData`) in [[`DebugGlobalData/index.tsx`](https://github.com/facebook/docusaurus/blob/main/DebugGlobalData/index.tsx)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.tsx).

Each page uses helper components like `DebugJsonView` to render collapsible JSON views. The TypeScript definitions in [[`plugin-debug.d.ts`](https://github.com/facebook/docusaurus/blob/main/plugin-debug.d.ts)](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-debug/src/plugin-debug.d.ts) declare these theme components, while the implementations live under `src/theme/`.

## Enabling the Docusaurus Debug Plugin

### Via the Classic Preset

Most Docusaurus sites use the classic preset, which includes the debug plugin automatically in development but disables it in production. To force enable it in production builds for troubleshooting, set the `debug` option to `true` as documented in [`plugin-debug.mdx`](https://github.com/facebook/docusaurus/blob/main/website/docs/api/plugins/plugin-debug.mdx):

```js
// docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Enable the debug plugin in production builds
        debug: true,
      },
    ],
  ],
};

```

### As a Standalone Plugin

For custom configurations without the classic preset, add `@docusaurus/plugin-debug` directly to your plugins array. Guard it with an environment check to restrict it to development:

```js
// docusaurus.config.js
export default {
  plugins: [
    // Only load in non-production environments
    process.env.NODE_ENV !== 'production' && '@docusaurus/plugin-debug',
  ].filter(Boolean),
};

```

To enable it unconditionally in production using the standalone method, omit the environment guard:

```js
// docusaurus.config.js
export default {
  plugins: ['@docusaurus/plugin-debug'],
};

```

The plugin accepts no configuration options; its presence alone activates the debugging interface.

## Investigating Build Issues with the Debug UI

Use this workflow to diagnose problems using the **Docusaurus debug plugin** interface:

1. **Start the development server** (`npm run start` or `yarn start`) or build the site with the plugin enabled.
2. **Navigate to `http://localhost:3000/__docusaurus/debug`** (adjust the port and base URL as needed).
3. **Inspect the Config page** to verify that [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) values loaded correctly, including theme and plugin configurations.
4. **Check the Routes page** to see the generated route hierarchy. This helps when pages return 404s or navigate incorrectly.
5. **Review the Content page** to examine the `AllContent` object. This reveals processed Markdown/MDX files, sidebar structures, and plugin-provided content that may be missing or malformed.
6. **Examine Global Data** to verify data passing between plugins, which often causes hydration mismatches in production builds.

**Security Warning:** The debug UI exposes internal site data including configuration details and file paths. As warned in the official Docusaurus documentation, disable the plugin in public production builds unless actively troubleshooting, as the exposed data could reveal sensitive implementation details.

## Summary

- The **Docusaurus debug plugin** (`@docusaurus/plugin-debug`) exposes internal site state at `/__docusaurus/debug` through a dedicated React interface.
- The plugin renders six diagnostic views—Config, Metadata, Registry, Routes, Content, and Global Data—via components in `packages/docusaurus-plugin-debug/src/theme/`.
- Enable it through the classic preset's `debug: true` option or by adding it manually to the plugins array.
- Use the Content and Routes pages to trace missing files or routing errors during builds.
- Never leave the debug plugin enabled in public-facing production environments due to data exposure risks.

## Frequently Asked Questions

### How do I access the Docusaurus debug UI?

After enabling `@docusaurus/plugin-debug` and starting your development server, visit `http://localhost:3000/__docusaurus/debug` (adjust for your base URL if configured). The interface appears as a navigation bar with links to Config, Routes, Content, and other diagnostic pages rendered by the plugin's theme components.

### Is the debug plugin safe to use in production?

The debug plugin exposes internal configuration, file paths, and data structures that could aid attackers in understanding your site architecture. While you can enable it in production by setting `debug: true` in the classic preset or removing environment guards from the standalone plugin configuration, you should disable it immediately after troubleshooting to prevent information leakage.

### What information does the Docusaurus debug plugin expose?

The plugin reveals the complete site configuration from [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js), the component registry, all generated router routes, the full content model including processed Markdown/MDX and sidebars, and the global data object shared between plugins. This data is rendered via React components like `DebugConfig` and `DebugContent` defined in the plugin's `src/theme/` directory.

### Can I configure options for the debug plugin?

No, the Docusaurus debug plugin accepts no configuration options. According to the source code in [`plugin-debug.d.ts`](https://github.com/facebook/docusaurus/blob/main/plugin-debug.d.ts) and the implementation files, the plugin activates solely based on its presence in the presets or plugins array. You cannot customize the routes or the displayed data through plugin options.