Troubleshooting Common Issues

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• docs.json
• api-reference/openapi.json
• quickstart.mdx
• development.mdx
• essentials/settings.mdx

This document provides guidance for diagnosing and resolving common issues encountered while developing and using the Mintlify documentation project. It covers problems related to the local development environment, configuration, and API request errors. The solutions and explanations are derived directly from the project's configuration and source files.

The troubleshooting process often involves checking the local development server, verifying the docs.json configuration, and understanding the expected API error responses. For a general overview of the setup process, refer to the Quickstart Guide.

Local Development Environment

Issues with the local preview environment are common. These usually stem from an outdated CLI version or an incorrect directory context.
Sources: README.md:14-28, development.mdx

Commands and Solutions

Command	Description	Troubleshooting Step
npm i -g mint	Installs the Mintlify CLI globally.	Run this first to ensure the CLI is available.
mint dev	Starts the local development server at http://localhost:3000.	Must be run at the root of the documentation project where docs.json is located.
mint update	Updates the Mintlify CLI to the most recent version.	Run this if the dev environment fails to start or behaves unexpectedly.

Sources: README.md:16-26, development.mdx

Common Problems

1. Dev Environment Not Running

If the mint dev command fails, the first step is to ensure your Mintlify CLI is up-to-date.

# Update the CLI to the latest version
mint update

Sources: README.md:25

2. Page Loads as a 404 Error

A 404 error in the local preview typically means the mint dev command was executed in the wrong directory. The command must be run from the project root, which is the directory containing the docs.json file. The CLI uses this file to build the documentation site structure.
Sources: README.md:27-28, docs.json

The following diagram illustrates the troubleshooting flow for the local development server.

API Reference Errors

When interacting with the API defined in this project, you may encounter errors. The API is designed to return structured error messages for 400-level responses.
Sources: api-reference/openapi.json

API Error Structure

All 400 "Bad Request" errors return a JSON object with a consistent structure, defined by the Error schema.

Field	Type	Description
error	integer (int32)	A numerical error code.
message	string	A human-readable string describing the error.

Sources: api-reference/openapi.json:156-168

Here is the JSON schema definition for an error response:

"Error": {
  "required": [
    "error",
    "message"
  ],
  "type": "object",
  "properties": {
    "error": {
      "type": "integer",
      "format": "int32"
    },
    "message": {
      "type": "string"
    }
  }
}

Sources: api-reference/openapi.json:156-168

Example Error Flow

The following sequence diagram shows a client making a POST request to /plants with invalid data, resulting in a 400 Bad Request response.

Common reasons for a 400 error include:

• Missing required fields in the request body (e.g., name for a new plant).
• Incorrect data types for fields (e.g., sending a string for id).

Sources: api-reference/openapi.json:113-142

Configuration and Customization Issues

Problems with the documentation's appearance, navigation, or branding are typically rooted in the docs.json configuration file.
Sources: docs.json, essentials/settings.mdx

Navigation Problems

If pages are missing from the sidebar or organized incorrectly, check the navigation object in docs.json. The structure is hierarchical: tabs contain groups, which contain a list of pages.

This diagram shows the navigation structure defined in docs.json.

To fix a missing page, ensure its file path (without the extension) is correctly listed in the pages array under the appropriate group.
Sources: docs.json:21-23, quickstart.mdx

Theme and Branding Issues

If the logo, favicon, or theme colors are not displaying correctly, verify the paths and values in docs.json.

Key	Description	Example Value
theme	Sets the overall theme.	"mint"
colors	Defines primary, light, and dark theme colors.	{ "primary": "#16A34A", ... }
favicon	Path to the site's favicon.	"/favicon.svg"
logo	Paths to the light and dark mode logos.	{ "light": "/logo/light.svg", ... }

Sources: docs.json:2-12, docs.json:65-68, essentials/settings.mdx

Ensure all file paths for assets like favicon and logo are correct and point to files within your project's public/static asset directory.
Sources: docs.json:12, docs.json:65-68