Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grigori.in/llms.txt

Use this file to discover all available pages before exploring further.

​
Mintlify Documentation Troubleshooting Guide

This guide helps resolve common issues when running Mintlify documentation on Windows.

​
Common Issues and Solutions

​
1. Mintlify CLI Update Check Error

Error:
Error: Command failed: npm view C:\Users\...\@mintlify\cli\bin\index.js version --silent
Solution: Install a stable version of Mintlify CLI: 
cd docs
npm install @mintlify/[email protected] --save-dev --force

​
2. Missing Favicon/Logo Files

Error:
ENOENT: no such file or directory, open 'favicon.svg'
Solution: Ensure these files exist in the docs directory:
  • favicon.svg
  • logo/light.svg
  • logo/dark.svg

​
3. Port Already in Use

Error:
Port 3000 is already in use
Solution: Mintlify will automatically try the next available port (3001, 3002, etc.) or you can specify a port: 
npx @mintlify/cli dev --port 3005

​
4. Windows Path Issues

Problem: Windows path separators causing issues with file resolution.
Solution: Use forward slashes in mint.json paths and ensure all referenced files use correct casing.

​
1. Install Dependencies

cd docs
npm install

​
2. Use NPX Commands

Always use npx to avoid global CLI issues:
npm run dev
# or
npx @mintlify/cli dev

​
3. Package.json Scripts

{
  "scripts": {
    "dev": "npx @mintlify/cli dev",
    "build": "npx @mintlify/cli build",
    "preview": "npx @mintlify/cli dev --no-open",
    "start": "npx @mintlify/cli dev --no-open"
  }
}

​
Alternative Solutions

Recommended for consistency
Create a Dockerfile in the docs directory:
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000

CMD ["npm", "run", "dev"]
Run with:
docker build -t doc-converter-docs .
docker run -p 3000:3000 doc-converter-docs

​
Deployment Options

Mintlify Cloud

  • Sign up at mintlify.com
  • Connect GitHub repository
  • Set docs path to /docs
  • Automatic deployment on push

Vercel

cd docs
npm install -g vercel
vercel --prod

Netlify

cd docs
npm install -g netlify-cli
netlify deploy --prod

​
Environment Variables

For development on Windows: 
$env:NODE_ENV="development"
$env:PORT="3000"

​
Debug Mode

Enable debug mode for more detailed error messages: 
$env:DEBUG="true"
npm run dev

​
Performance Tips

Add to .gitignore:
node_modules/
_site/
.mintlify/
Use local dependencies instead of global CLI
If issues persist:
rm -rf node_modules package-lock.json
npm install

​
Getting Help

If you encounter issues not covered here:
1

Check documentation

Check the Mintlify documentation
2

Review error logs

Review the error logs carefully
3

Use verbose flag

Try running commands with --verbose flag
4

Check Node.js version

Check Node.js version compatibility (requires Node 18+)

​
Version Information

Mintlify CLI

4.0.500 (stable version for Windows)

Node.js

18+ required

npm

Latest stable version recommended

​
Quick Commands Reference

npm run dev