mintlify__docs/cli/troubleshooting.mdx

---
title: "Troubleshooting local preview"
description: "Fix common problems with mint dev, including port conflicts, build errors, missing pages, and network issues."
keywords: ["mint dev troubleshooting", "local preview", "CLI errors", "build errors", "port conflict"]
---

Run `mint dev` from your documentation directory to start a local preview at `http://localhost:3000`.

For CLI installation problems, see [Install the CLI](/cli/install#troubleshooting).

<AccordionGroup>

  <Accordion title="mint dev won't start or crashes immediately">
    1. **Confirm you're in the right directory**: Run `mint dev` from the root of your documentation project — the directory that contains `docs.json` (or `mint.json` for older projects).
    2. **Delete the cache and retry**: Go to your home directory and delete the `~/.mintlify` folder, then run `mint dev` again.

        ```bash
        rm -rf ~/.mintlify
        mint dev
        ```

    3. **Check your Node.js version**: The CLI requires Node.js v20.17.0 or later. Run `node -v` to check.
    4. **Update the CLI**: Run `mint update` to get the latest version. If `mint update` isn't available, reinstall:

        ```bash npm
        npm i -g mint@latest
        ```
  </Accordion>

  <Accordion title="Port 3000 is already in use">
    Another process is using port 3000. Find and stop it, or use a different port.

    **Find the process using port 3000:**

    ```bash macOS / Linux
    lsof -ti :3000 | xargs kill
    ```

    ```bash Windows (PowerShell)
    Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process
    ```

    After stopping the process, run `mint dev` again.
  </Accordion>

  <Accordion title="Pages are missing or showing a 404 in the local preview">
    1. **Check your navigation config**: Every page must be referenced in `docs.json` under `navigation` to appear. Confirm the file path in `docs.json` matches the actual file path, without the `.mdx` extension.
    2. **Check the file exists**: Verify the `.mdx` file is in the location you expect.
    3. **Check for typos in frontmatter**: A malformed frontmatter block (for example, unclosed quotes or missing `---` delimiters) can prevent a page from rendering.
    4. **Restart `mint dev`**: Some file changes require a restart. Stop the process with `Ctrl+C` and run `mint dev` again.
  </Accordion>

  <Accordion title="The local preview doesn't match the live site">
    This is usually caused by an outdated CLI version. Update to the latest:

    ```bash
    mint update
    ```

    If `mint update` doesn't work, reinstall:

    ```bash npm
    npm i -g mint@latest
    ```
  </Accordion>

  <Accordion title="I see broken links or images in the local preview">
    Run `mint broken-links` in your documentation directory to get a full list of broken internal links:

    ```bash
    mint broken-links
    ```

    For images, confirm:
    - The image file exists at the path referenced in the MDX.
    - The path is root-relative (for example, `/images/screenshot.png`) rather than relative (for example, `../../images/screenshot.png`).
    - The filename and extension match exactly (paths are case-sensitive on Linux).
  </Accordion>

  <Accordion title="OpenAPI pages are blank or missing endpoints">
    1. **Validate your OpenAPI spec**: Run `mint validate` in your documentation directory to check for spec errors. See [API playground troubleshooting](/api-playground/troubleshooting) for a full list of common issues.
    2. **Check the `docs.json` reference**: Confirm the `openapi` field in `docs.json` points to the correct spec file and that the file exists.
    3. **Check for unsupported OpenAPI version**: Mintlify supports OpenAPI 3.x only. OpenAPI 2.0 (Swagger) specs must be converted first.
  </Accordion>

  <Accordion title="mint dev can't connect to Mintlify servers (firewall or VPN)">
    The CLI contacts Mintlify servers to download the preview client and check for updates. If you're on a corporate network or VPN:

    1. Ask your IT administrator to add `releases.mintlify.com` to the network allowlist.
    2. If `mint version` shows the client version as `none`, this is the cause.
    3. As a workaround, run `mint dev` from a network without the restriction, or download the client on an unrestricted network and copy it to the restricted machine.
  </Accordion>

  <Accordion title="Changes aren't reloading automatically">
    `mint dev` watches your files for changes and reloads automatically. If it stops updating:

    1. Check that you saved the file — some editors require an explicit save step.
    2. Check the terminal output for errors. A syntax error in an MDX file or `docs.json` can halt the watcher.
    3. Stop and restart `mint dev`.
    4. On macOS, if you have a large number of files, you may hit the system file-watcher limit. Increase it with:

        ```bash
        sudo sysctl kern.maxfiles=1048576 kern.maxfilesperproc=524288
        ```
  </Accordion>

  <Accordion title="mint dev works locally but deployment fails">
    A successful local preview doesn't guarantee a clean deployment, because the CLI and deployment environment can have minor differences. Common causes of deploy-only failures:

    - **Broken links**: Run `mint broken-links` locally to catch these before pushing.
    - **Missing files**: A file referenced in navigation or an image path may exist locally but wasn't committed to Git.
    - **docs.json syntax errors**: Validate your JSON with a linter or the built-in `mint validate` command.

    Check the build error in your [dashboard](https://app.mintlify.com/) for the specific failure message. After fixing the issue, push again to trigger a new deployment, or manually trigger one from the dashboard.
  </Accordion>

</AccordionGroup>

If none of these steps resolve your issue, contact [Mintlify support](https://mintlify.com/docs/contact-support).