claude-multi
Back to FAQ
Troubleshooting

How do I troubleshoot broken instances?

claude-multi has a health monitoring system that scans all your instances and surfaces problems. It won’t fix things without asking, it shows you what’s wrong and suggests how to fix it.

Running health checks

In the TUI, a warning banner appears at the top of the main menu when issues are detected. Press ! to jump straight to the health screen, which lists everything it found across all instances.

You can also see health status when listing instances:

Terminal window
claude-multi list

What gets checked

ProblemWhat happenedHow to fix
Config directory missingInstance dir was deleted outside claude-multiRemove the instance from the registry, or recreate the directory
Binary not foundWrapper script was deletedRe-create the instance or run claude-multi sync
Corrupted settings.jsonInvalid JSON in the config fileFix or delete the corrupted file
Broken symlinksPlugin/skill links point to nonexistent targetsRun claude-multi fix-symlinks
Migration failedConfig schema migration was interruptedThe health screen offers retry/restore options

Common fixes

Terminal window
claude-multi fix-symlinks

Repairs symlinks across all instances. Target specific ones with claude-multi fix-symlinks deepseek glm.

Corrupted config

If a settings file is too far gone, remove and recreate the instance:

Terminal window
claude-multi remove broken-instance
claude-multi add broken-instance --provider deepseek --api-key sk-your-key

Your conversation history lives in ~/.claude-multi/broken-instance/projects/, it’s separate from config, so back it up before removing if you want to keep it.

Migration failures

Migrations create backups before touching anything. If one fails:

  1. Check ~/.claude-multi/config.json for migration status flags
  2. Look for .bak files in the instance directory
  3. The health screen will show the specific error and offer to retry or restore from backup

More info