Troubleshooting

Installation Issues

npm: command not found

Node.js and npm are not installed.Solution:

macOS
Linux
Windows

# Using Homebrew
brew install node

# Or download from nodejs.org

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

Verify installation:

node --version
npm --version

EACCES permission denied errors

You don’t have permission to install global packages.Solution 1: Configure npm to use a different directory (Recommended)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Solution 2: Fix npm permissions

sudo chown -R $USER /usr/local/lib/node_modules
sudo chown -R $USER /usr/local/bin

Solution 3: Use npx (no installation needed)

npx megallm@latest

Old version being used

npm cache has an outdated version.Solution:

# Clear npm cache
npm cache clean --force

# Run latest version
npx megallm@latest

# Or update global installation
npm update -g megallm

# Verify version
npx megallm@latest --version

Configuration Issues

Configuration not loading

Configuration files aren’t being read.Diagnosis:

# Check if files exist
ls -la ~/.claude/settings.json
ls -la ~/.codex/config.toml
ls -la ~/.config/opencode/opencode.json

# Check project-level configs
ls -la .claude/settings.json
ls -la opencode.json

Solutions:1. Verify file locations:

# Claude Code
~/.claude/settings.json          # System
./.claude/settings.json          # Project

# Codex
~/.codex/config.toml             # System only

# OpenCode
~/.config/opencode/opencode.json # System
./opencode.json                  # Project

2. Check file permissions:

chmod 644 ~/.claude/settings.json
chmod 644 ~/.codex/config.toml
chmod 644 ~/.config/opencode/opencode.json

3. Validate syntax:

# JSON files
jq . ~/.claude/settings.json

# TOML files
cat ~/.codex/config.toml
# (install toml-cli for validation)

4. Check working directory:

pwd
# For project-level configs, you must be in the project directory

API key not recognized

API key isn’t being read from config or environment.Diagnosis:

# Check environment variables
echo $ANTHROPIC_API_KEY
echo $MEGALLM_API_KEY

# Check config files
jq '.env.ANTHROPIC_API_KEY' ~/.claude/settings.json
cat ~/.codex/config.toml | grep MEGALLM_API_KEY
jq '.provider.anthropic.options.apiKey' ~/.config/opencode/opencode.json

Solutions:1. Reload shell configuration:

source ~/.bashrc  # or ~/.zshrc
# Or restart your terminal

2. Verify API key format:

Must start with sk-mega-
At least 20 characters long
No spaces or quotes around the key

3. Set environment variable manually:

# Claude Code
export ANTHROPIC_API_KEY="sk-mega-your-key"

# Codex/Windsurf and OpenCode
export MEGALLM_API_KEY="sk-mega-your-key"

4. Test API key directly:

curl -H "Authorization: Bearer sk-mega-your-key" \
     https://ai.megallm.io/v1/models

Wrong base URL being used

Tool is connecting to the wrong API endpoint.Diagnosis:

# Check environment variables
echo $ANTHROPIC_BASE_URL

# Check config files
jq '.env.ANTHROPIC_BASE_URL' ~/.claude/settings.json
cat ~/.codex/config.toml | grep base_url
jq '.provider.anthropic.options.baseURL' ~/.config/opencode/opencode.json

Solution:Ensure base URL is exactly:

https://ai.megallm.io

Common mistakes:

# <Icon icon="xmark" /> Wrong
https://ai.megallm.io/      # Trailing slash
https://ai.megallm.io/v1/   # Extra /v1/ (Codex/OpenCode only)
http://ai.megallm.io        # HTTP instead of HTTPS

# <Icon icon="check" /> Correct for Claude Code
https://ai.megallm.io

# <Icon icon="check" /> Correct for Codex/OpenCode
https://ai.megallm.io/v1

Fix:

# Claude Code
export ANTHROPIC_BASE_URL="https://ai.megallm.io"

# Update config files with correct URL

Configuration priority issues

Wrong configuration is being used.Understanding Priority:

Environment Variables (Highest)

Variables set in shell always take precedence

Project-Level Config

Config in current directory (.claude/, opencode.json)

System-Level Config (Lowest)

Global config in home directory (~/.claude/, ~/.codex/, ~/.config/opencode/)

Diagnosis:

# Check what's set where
echo "ENV VAR: $ANTHROPIC_API_KEY"
echo "PROJECT: $(jq -r '.env.ANTHROPIC_API_KEY' .claude/settings.json 2>/dev/null)"
echo "SYSTEM: $(jq -r '.env.ANTHROPIC_API_KEY' ~/.claude/settings.json 2>/dev/null)"

Solution:Remove conflicting configurations or use the right priority level:

# To force project-level, unset environment variable
unset ANTHROPIC_API_KEY

# To force environment variable, set it
export ANTHROPIC_API_KEY="sk-mega-your-key"

CLI Execution Issues

CLI hangs or freezes

CLI is stuck during execution.Solutions:1. Cancel and retry:

# Press Ctrl+C to cancel
# Then run again
npx megallm@latest

2. Check for prompts: The CLI may be waiting for input. Look for questions like:

“Enter your API key:”
“Continue? (y/n)”

3. Run with debug mode:

DEBUG=* npx megallm@latest
# Shows detailed logs of what's happening

4. Check for background processes:

# Check if another instance is running
ps aux | grep megallm

Tool not detected

CLI says a tool isn’t installed but it is.Diagnosis:

# Check if tool is globally installed
npm list -g --depth=0 | grep claude
npm list -g --depth=0 | grep codex
npm list -g --depth=0 | grep opencode

# Check if command is available
which claude-code
which codex
which windsurf
which opencode

Solutions:1. Ensure global installation:

npm install -g @anthropic-ai/claude-code
npm install -g @codeium/windsurf
npm install -g opencode

2. Restart terminal:

# Close and reopen terminal
# Or reload shell config
source ~/.bashrc

3. Check PATH:

echo $PATH
# Should include npm global bin directory

4. Manual configuration: If detection fails, configure manually without the CLI.

Permission denied when creating config files

CLI can’t write to configuration directories.Solution:macOS/Linux:

# Fix ownership
sudo chown -R $USER ~/.claude ~/.codex ~/.config/opencode

# Fix permissions
chmod -R 755 ~/.claude ~/.codex ~/.config/opencode

# For project configs
chmod -R 755 .claude

Windows: Run terminal as Administrator or fix folder permissions in File Explorer.

API Connection Issues

API connection failed

Can’t connect to MegaLLM API.Diagnosis:

# Test API connection
curl -v https://ai.megallm.io/v1/models \
  -H "Authorization: Bearer sk-mega-your-key"

Solutions:1. Check internet connection:

ping -c 3 ai.megallm.io

2. Check firewall/proxy:

# If behind a proxy, set npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

3. Verify API key:

Go to megallm.io/dashboard
Generate a new API key
Update your configuration

4. Check API status: Visit megallm.io/status for service status

401 Unauthorized error

API key is invalid or expired.Solution:1. Generate new API key:

Go to megallm.io/dashboard
Create new API key
Update configuration

2. Update config:

# Run CLI again to reconfigure
npx megallm@latest

# Or update manually
jq '.env.ANTHROPIC_API_KEY = "new-key"' ~/.claude/settings.json > tmp.json && mv tmp.json ~/.claude/settings.json

3. Clear and reset:

# Remove old config
rm ~/.claude/settings.json ~/.claude.json
rm ~/.codex/config.toml
rm ~/.config/opencode/opencode.json

# Run CLI fresh
npx megallm@latest

Rate limit exceeded

Too many API requests in a short time.Solution:1. Wait and retry: Rate limits reset after a period (usually 1 minute).2. Check your usage:

Go to megallm.io/dashboard
View API usage statistics

3. Upgrade plan: If you consistently hit rate limits, consider upgrading your plan.4. Implement retry logic:

# In your application code
import time
import openai

for i in range(3):
    try:
        response = client.chat.completions.create(...)
        break
    except openai.RateLimitError:
        if i < 2:
            time.sleep(2 ** i)  # Exponential backoff
        else:
            raise

Shell and Environment Issues

Environment variables not persisting

Variables are lost after closing terminal.Solution:Environment variables must be added to shell config files:

# Determine your shell
echo $SHELL

# bash: ~/.bashrc or ~/.bash_profile
echo 'export ANTHROPIC_API_KEY="sk-mega-..."' >> ~/.bashrc
source ~/.bashrc

# zsh: ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-mega-..."' >> ~/.zshrc
source ~/.zshrc

# fish: ~/.config/fish/config.fish
echo 'set -x ANTHROPIC_API_KEY "sk-mega-..."' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Verify:

# Close terminal
# Open new terminal
echo $ANTHROPIC_API_KEY
# Should show your key

Shell config not reloading

Changes to shell config aren’t taking effect.Solutions:1. Reload shell config:

# bash
source ~/.bashrc

# zsh
source ~/.zshrc

# fish
source ~/.config/fish/config.fish

2. Restart terminal: Close and reopen your terminal application.3. Check for syntax errors:

# bash/zsh
bash -n ~/.bashrc  # Check syntax
bash -n ~/.zshrc

# fish
fish -n ~/.config/fish/config.fish

4. Check file was actually modified:

tail -20 ~/.bashrc
# Should show your recent additions

Platform-Specific Issues

macOS: Command not found after installation

PATH isn’t updated for npm global packages.Solution:

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

# Or for bash
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Windows: PowerShell execution policy

Scripts are blocked by PowerShell execution policy.Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then run CLI
npx megallm@latest

Linux: /usr/local/lib permission issues

Can’t install global packages due to permissions.Solution:

# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Option 2: Change npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Advanced Troubleshooting

Enable Debug Mode

Get detailed logs to diagnose issues:

# Run with debug output
DEBUG=* npx megallm@latest

# Or set environment variable
export DEBUG=*
npx megallm@latest

Complete Reset

If all else fails, completely reset configuration:

# 1. Backup existing configs
mkdir ~/megallm-backup
cp -r ~/.claude ~/megallm-backup/
cp -r ~/.codex ~/megallm-backup/
cp -r ~/.config/opencode ~/megallm-backup/

# 2. Remove all configs
rm -rf ~/.claude
rm -rf ~/.codex
rm -rf ~/.config/opencode
rm -rf .claude
rm -f opencode.json

# 3. Remove environment variables
# Edit ~/.bashrc or ~/.zshrc and remove lines with:
# - ANTHROPIC_BASE_URL
# - ANTHROPIC_API_KEY
# - MEGALLM_API_KEY

# 4. Reload shell
source ~/.bashrc

# 5. Run CLI fresh
npx megallm@latest

Collect Diagnostic Information

For support requests, collect this information:

# System info
uname -a
node --version
npm --version

# Check configs
ls -la ~/.claude/ ~/.codex/ ~/.config/opencode/
cat ~/.claude/settings.json
cat ~/.codex/config.toml
cat ~/.config/opencode/opencode.json

# Check environment
env | grep -E "ANTHROPIC|MEGALLM"

# Run with debug
DEBUG=* npx megallm@latest 2>&1 | tee megallm-debug.log

Still Need Help?

If you’re still experiencing issues:

Check FAQ

Common questions and answers

Email Support

Get help from our team

GitHub Issues

Report bugs or search existing issues

Discord Community

Ask the community

Prevention Tips

Keep Tools Updated

Regularly update Node.js, npm, and AI tools

Backup Configs

Keep backups of working configurations

Test After Changes

Verify configuration after manual edits

Use Version Control

Commit working configs (without API keys)

Getting Started

Configuration

Guides

Troubleshooting

Installation Issues

Configuration Issues

CLI Execution Issues

API Connection Issues

Shell and Environment Issues

Platform-Specific Issues

Advanced Troubleshooting

Enable Debug Mode

Complete Reset

Collect Diagnostic Information

Still Need Help?

Check FAQ

Email Support

GitHub Issues

Discord Community

Prevention Tips

Keep Tools Updated

Backup Configs

Test After Changes

Use Version Control

Getting Started

Configuration

Guides

Documentation Index

​Installation Issues

​Configuration Issues

​CLI Execution Issues

​API Connection Issues

​Shell and Environment Issues

​Platform-Specific Issues

​Advanced Troubleshooting

​Enable Debug Mode

​Complete Reset

​Collect Diagnostic Information

​Still Need Help?

Check FAQ

Email Support

GitHub Issues

Discord Community

​Prevention Tips

Keep Tools Updated

Backup Configs

Test After Changes

Use Version Control

Installation Issues

Configuration Issues

CLI Execution Issues

API Connection Issues

Shell and Environment Issues

Platform-Specific Issues

Advanced Troubleshooting

Enable Debug Mode

Complete Reset

Collect Diagnostic Information

Still Need Help?

Prevention Tips