---
title: "Common Issues"
description: "This page covers common issues and questions you may encounter while using the Fumadocs CLI. Whether you are setting up your project, adding components, or exporting files, use this guide to troubl..."
last_updated: "2026-07-02T09:48:33.577077+00:00"
canonical_url: "https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/guide/troubleshooting/common-issues"
---

This page covers common issues and questions you may encounter while using the Fumadocs CLI. Whether you are setting up your project, adding components, or exporting files, use this guide to troubleshoot standard behaviors.

## Configuration Already Exists
When you run the command to initialize your project, the tool creates a configuration file in your directory. If you try to run the initialization command again in a folder that already contains this file, the system will prevent you from overwriting it.

> [!NOTE]
> If you need to change your settings, you can manually edit your configuration file instead of running the initialization command again.

## Exporting to EPUB
The CLI allows you to export your documentation to EPUB format. To ensure this works correctly, follow these requirements:

1. **Build First:** You must run your production build process before triggering the EPUB export. The tool needs the compiled assets to generate the file.
2. **Framework Selection:** You are required to specify your framework using the `--framework` flag. Supported options include `next`, `tanstack-start`, `react-router`, and `waku`.

> [!WARNING]
> If you omit the `--framework` flag, the export process will fail because it cannot determine how to correctly package your documentation.

## Troubleshooting Component Registry
When using the `add` command to bring new components into your project, or the `customise` command to adjust layouts, the CLI connects to a registry to fetch files. If you run into issues, consider the following:

*   **Registry URL:** By default, the CLI connects to the official Fumadocs registry. If you are using a custom local directory, ensure you provide the correct `--dir` path.
*   **Shortcuts:** You can use shorthand references like `:preview` or `:dev` if you are testing your own components against local instances or preview environments.

## File Structure Generation
You can visualize and generate a structured hierarchy of your files. The CLI converts your folder structure into a format suitable for your documentation site (either as JavaScript/TypeScript or MDX).

*   **Format Choice:** The tool automatically detects if you want a JavaScript/TypeScript file based on the output file extension you provide (e.g., `.js`, `.tsx`, `.jsx`). 
*   **Root Nodes:** By default, the root folder of your project is included in the output. If you want to exclude the top-level directory, use the `--no-root` flag.

> [!TIP]
> If you are not sure if your input is valid JSON, just pass the directory path (e.g., `./`) to the command, and it will automatically read the folder structure for you.

## Quick Reference for CLI Options

| Command | Purpose | Key Flag |
| :--- | :--- | :--- |
| `add` | Download components | `--dir` |
| `customise` | Modify layouts | `--dir` |
| `export` | Create EPUB file | `--framework` |

> [!IMPORTANT]
> Always ensure your environment is set up correctly by running commands from your project's root folder to avoid path-related errors.

## Related

- [Quickstart Guide](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/guide/getting-started/quickstart-guide)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/llms.txt) for all pages in this wiki.