Troubleshooting

Solutions to common problems you might encounter.

Common Issues

Build Errors

Module not found errors

If you see errors like Cannot find module 'fumadocs-ui':

Clear your node_modules and lock file:

rm -rf node_modules package-lock.json

Reinstall dependencies:

npm install

If the issue persists, try clearing the Next.js cache:

rm -rf .next
npm run dev

MDX parsing errors

MDX has strict parsing rules. Common issues include:

Unclosed JSX tags
Missing imports for custom components
Invalid JavaScript expressions in curly braces

Solution: Check your MDX syntax and ensure all components are properly imported.

Component not defined errors

If you see Expected component 'X' to be defined:

Make sure the component is imported in mdx-components.tsx
Verify the import path is correct
Check that the component is exported from its source

// mdx-components.tsx
import { MyComponent } from 'fumadocs-ui/components/my-component';

export function getMDXComponents(components) {
  return {
    ...defaultComponents,
    MyComponent, // Register here
    ...components,
  };
}

Runtime Errors

Hydration Errors: These occur when server and client render differently.

Common causes:

Using browser-only APIs during SSR
Conditional rendering based on window/document
Date/time formatting differences

Solution:

'use client'

import { useEffect, useState } from 'react';

export function ClientComponent() {
  const [mounted, setMounted] = useState(false);
  
  useEffect(() => {
    setMounted(true);
  }, []);
  
  if (!mounted) return null;
  
  // Client-only code here
}

Performance Issues

Solutions:

Use Next.js 15+ with Turbopack
Enable SWC minification
Reduce the number of pages generated at build time

// next.config.mjs
export default {
  experimental: {
    turbo: true,
  },
};

Optimize bundle size:

Use dynamic imports for large components
Enable tree shaking
Analyze bundle with @next/bundle-analyzer

import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(() => import('./Heavy'), {
  loading: () => <p>Loading...</p>,
});

Increase Node.js memory:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

This allocates 4GB of memory to the build process.

Debugging Tips

Enable Verbose Logging

DEBUG=* npm run dev

Check Your Configuration

Verify source.config.ts is correct

Check next.config.mjs for conflicts

Review mdx-components.tsx exports

Clear All Caches

rm -rf .next node_modules .turbo
npm install
npm run dev

Still Having Issues?

If you're still experiencing problems, try these resources:

GitHub Issues

Discord Community

Documentation

Error Reference

Error Code	Description	Solution
`ENOTFOUND`	DNS/Network error	Check internet connection
`EACCES`	Permission denied	Run with appropriate permissions
`EADDRINUSE`	Port already in use	Use a different port or kill the process
`MODULE_NOT_FOUND`	Missing dependency	Run `npm install`

Resolved your issue? Great! Check out more guides to enhance your documentation.

Troubleshooting

GitHub Issues

Discord Community

Documentation

On this page