Troubleshooting

`claude-<name>` command not found

Your global binary directory is not on PATH. The exact location depends on your package manager, and the TUI prints it when it creates an instance.

Common locations:

Runtime	Binary directory
Bun	`~/.bun/bin/`
npm (Linux/macOS)	`~/.local/bin/` or `/usr/local/bin/`
pnpm	`~/.local/share/pnpm/`
Deno	`~/.deno/bin/`

Fix:

# zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Replace ~/.local/bin with the actual path from your instance creation output.

Broken plugin or skill symlinks

If you moved or deleted ~/.claude/, the symlinks in auto-synced instances now point at nothing.

Fix from TUI: Select Re-sync symlinks from the main menu. Pick the broken instance (or all).

Fix from CLI:

# Fix a specific instance
claude-multi fix-symlinks deepseek

# Fix all instances
claude-multi fix-symlinks --all

A yellow or red banner at the top of the main menu means claude-multi found problems. Press ! to open the health screen.

Common health issues:

Problem	Cause	Fix
Config directory missing	Instance dir was deleted outside claude-multi	Remove the instance or recreate the directory
Binary not found	Wrapper script was deleted	Re-create the instance
Corrupted settings.json	Invalid JSON in the config file	Fix or delete the corrupted file, then recreate
Broken symlinks	Plugin/skill links point to missing targets	Run `fix-symlinks`
Migration failed	Config schema migration was interrupted	Health screen offers retry/restore from backup

Ink TUI doesn’t render properly

Some terminals, including older SSH clients, do not handle the Ink-based React TUI well.

Fix: Force the simpler prompts-based UI:

CLAUDE_MULTI_INK=false claude-multi

Same flows, simpler rendering.

API key not working

If Claude Code can’t authenticate with your provider:

Check the key is set: claude-multi info <name> shows the instance’s settings
Check the base URL: Make sure you used the right provider template for your account type. MiMo and Qwen have separate templates for pay-per-token and subscription plans, and the wrong one points at the wrong endpoint
Verify the settings file: Open ~/.claude-<name>/settings.json and check the env block

# Check what's configured
cat ~/.claude-multi/deepseek/settings.json | jq .env

Wrong provider endpoint

Some providers use different base URLs for pay-per-token vs. subscription plans:

Provider	Pay-per-token	Subscription
Xiaomi MiMo	`mimo` template	`mimo-token` template (different domain)
Alibaba Qwen	`qwen` template	`qwen-coding` template (different subdomain)
GLM (Z.ai)	No Anthropic-compatible URL	`glm` template (coding plan only)

If you are on a subscription plan but used the pay-per-token template, or the other way around, your API key will not authenticate. Remove the instance and recreate it with the correct template.

Duplicate instance name

Error: Instance 'deepseek' already exists

Instance names must be unique. Either pick a different name or remove the existing one first:

claude-multi remove deepseek
claude-multi add deepseek --provider deepseek --api-key sk-...

MCP server not working

If an MCP server fails to connect:

Verify the config: claude-multi mcp verify checks that referenced executables and paths exist
Check for collisions: claude-multi plugins check-collisions <instance> <plugin-id> catches two plugins registering the same MCP server name
Inspect the config: Open ~/.claude-<name>/settings.json and look at the mcpServers field

Config migration failed

If a migration was interrupted:

Check ~/.claude-multi/config.json for migrationStatus flags
Look for .bak files in the instance directory
The health screen (press ! in the TUI) shows the specific error and offers retry or restore options

Migrations create backups before touching anything. claude-multi keeps the last 3 backup sets in ~/.claude-multi/backups/.

Provider template did not update

After upgrading claude-multi, run:

claude-multi doctor check
claude-multi doctor fix

The check reports provider settings that no longer match the current template. The fix backs them up, then updates the model slots and template settings. It leaves your API keys and custom tuning values alone.

Update check not working

Update checks are opt-in. Enable them:

export CLAUDE_MULTI_UPDATE_CHECK=true
claude-multi

Or check manually:

claude-multi version

Still stuck?

Run claude-multi list to see all instances and their status
Run claude-multi info <name> for detailed config of a specific instance
Check the GitHub issues for known problems
Open a new issue with your claude-multi version output and the content of ~/.claude-multi/config.json