MiMo Code Troubleshooting

Solutions for common MiMo Code issues. Search or browse by category.

Install Issues

npm Permission Error (EACCES)

npm ERR! code EACCES
npm ERR! syscall mkdir
Error: EACCES: permission denied

Fix: Reinstall Node with a version manager (recommended) or fix npm permissions:

# Option A: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20; nvm use 20
npm install -g @mimo-ai/cli

# Option B: Fix npm global permissions (quick)
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

"mimo: command not found"

zsh: command not found: mimo
bash: mimo: command not found

Fix: npm global bin is not in PATH.

# Add npm global bin to PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or locate and add manually
npm config get prefix
# then add that path + /bin to your PATH

Node.js Version Too Old

Error: MiMo Code requires Node.js >= 18.0.0
Current version: v16.x.x

Fix: Upgrade Node.js to 18+.

# Using nvm
nvm install 20; nvm use 20

# Using Homebrew (macOS)
brew uninstall node; brew install node@20

# Using apt (Linux)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Model Connection Issues

API Authentication Error (401)

Error: API request failed with status 401
Invalid API key or authentication

Fix: Check your API key environment variable.

# Verify the key is set
echo $MIMOCODE_API_KEY

# Re-set it
export MIMOCODE_API_KEY=your-actual-key

# Check key format (no extra spaces or quotes)
# OpenRouter keys start with "sk-or-v1-"
# DeepSeek keys from platform.deepseek.com
# Anthropic keys start with "sk-ant-"

Connection Refused to Local Model

Error: connect ECONNREFUSED 127.0.0.1:11434

Fix: Ollama is not running.

# Start Ollama
ollama serve

# In a new terminal, verify
ollama list

# Pull a model if needed
ollama pull qwen2.5-coder:14b

Wrong API Base URL (404)

Error: API request failed with status 404
Not Found

Fix: Check your MIMOCODE_API_BASE includes the full path.

# Correct OpenRouter
export MIMOCODE_API_BASE=https://openrouter.ai/api/v1

# Correct DeepSeek
export MIMOCODE_API_BASE=https://api.deepseek.com

# Correct local Ollama
export MIMOCODE_API_BASE=http://localhost:11434/v1

# Verify:
curl $MIMOCODE_API_BASE/models -H "Authorization: Bearer $MIMOCODE_API_KEY"

Rate Limit / Credit Exhausted (429)

Error: API request failed with status 429
Rate limit exceeded or credits exhausted

Fix: You have hit the token/rate limit.

# For OpenRouter: check usage at openrouter.ai/usage
# For DeepSeek: top up at platform.deepseek.com
# For Token Plan: upgrade or wait for reset

# Switch to a cheaper model temporarily
export MIMOCODE_MODEL=deepseek-chat

# Or disable Max Mode to reduce token usage
export MIMOCODE_MAX_MODE=false

API Timeout

Error: Request timeout
ETIMEDOUT or ECONNABORTED

Fix: Network or provider latency.

# Check your internet connection
curl -I https://api.deepseek.com

# If behind a proxy, set:
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

# Some regions block API providers; use a VPN
# Or switch to another provider:
export MIMOCODE_PROVIDER=openai_compatible
export MIMOCODE_API_BASE=https://openrouter.ai/api/v1

Config & Environment

Provider Not Configured

Error: MIMOCODE_PROVIDER is not set
Please configure a model provider

Fix: Set the required environment variables.

# Choose one provider:
# OpenRouter
export MIMOCODE_PROVIDER=openai_compatible
export MIMOCODE_API_BASE=https://openrouter.ai/api/v1
export MIMOCODE_API_KEY=your-key
export MIMOCODE_MODEL=deepseek/deepseek-chat

# For persistence, add to ~/.zshrc or ~/.bashrc

Invalid Model Name

Error: Model not found
400 Bad Request — unknown model

Fix: Use the correct model identifier.

# OpenRouter model names (check openrouter.ai/models):
export MIMOCODE_MODEL=deepseek/deepseek-chat
export MIMOCODE_MODEL=anthropic/claude-sonnet-4-20250514
export MIMOCODE_MODEL=openai/gpt-4.1
export MIMOCODE_MODEL=qwen/qwen-2.5-coder-32b-instruct

# DeepSeek direct:
export MIMOCODE_MODEL=deepseek-chat

# Local Ollama:
export MIMOCODE_MODEL=qwen2.5-coder:14b

Agent Behavior

Agent Forgets Context

The agent doesn't remember previous instructions or project context.

Fix: Improve memory setup.

# 1. Run /init in project root
mimo
/init

# 2. Create or update AGENTS.md
# Add project rules, conventions, tech stack

# 3. Use /memory to view current memory
/memory

# 4. Use /dream to consolidate after long sessions
/dream

# 5. Create checkpoints before major changes
/checkpoint "before refactor"

Max Mode Too Slow or Expensive

Max Mode uses 4-5x tokens and is slow for simple tasks.

Fix: Use Max Mode selectively.

# Disable Max Mode for simple tasks:
export MIMOCODE_MAX_MODE=false

# Only enable for complex refactors:
export MIMOCODE_MAX_MODE=true

# Or use Max Mode per-session:
mimo --max-mode

# For routine tasks like comments or formatting, keep it off

Privacy Concerns — Telemetry

Telemetry is enabled by default and may send usage data.

Fix: Disable telemetry.

# Disable telemetry
export MIMOCODE_ENABLE_ANALYSIS=false

# Add to shell profile for persistence:
echo 'export MIMOCODE_ENABLE_ANALYSIS=false' >> ~/.zshrc

# For fully private work, use local models:
export MIMOCODE_PROVIDER=openai_compatible
export MIMOCODE_API_BASE=http://localhost:11434/v1
export MIMOCODE_API_KEY=ollama

MCP Server Not Working

MCP tools not appearing or connection failing.

Fix: Check MCP server config and startup.

# Verify MCP support is enabled:
export MIMOCODE_MCP_ENABLED=true

# Check your MCP server config file:
# ~/.mimocode/mcp_servers.json or .mimocode/mcp_servers.json

# Test your MCP server independently:
npx @modelcontextprotocol/server-filesystem /path/to/allowed/dir

# Common MCP server examples:
# Filesystem: npx @modelcontextprotocol/server-filesystem /path
# GitHub: npx @modelcontextprotocol/server-github
# Postgres: npx @modelcontextprotocol/server-postgres postgresql://...

Still Having Issues?

Check the official GitHub issues, or verify your setup with the Config Generator.

Independent troubleshooting guide. Solutions based on community reports and documentation as of June 2026. Always check official docs for the latest.