Troubleshooting

Common issues and solutions when using napari MCP server with AI assistants.

🛠️ CLI Installer Issues

The napari-mcp-install CLI tool automates configuration. Here are common issues and solutions.

Installation Problems

!!! failure "napari-mcp-install: command not found" Problem: The CLI installer command isn't available after installation.

**Solutions:**
```bash
# Reinstall the package
pip install --force-reinstall napari-mcp

# Verify installation
pip list | grep napari-mcp

# Check if it's in your PATH
which napari-mcp-install

# Try running with python -m
python -m napari_mcp.cli.main --help
```

!!! failure "ImportError when running installer" Problem: Missing dependencies (typer, rich).

**Solution:**
```bash
# Reinstall with all dependencies
pip install --upgrade napari-mcp

# Or install dependencies manually
pip install typer rich
```

Configuration Issues

!!! failure "Configuration file not created" Problem: Installer runs but config file doesn't exist.

**Solutions:**
1. **Check what would be created:**
   ```bash
   napari-mcp-install install <app> --dry-run
   ```

2. **Verify installer detected correct path:**
   ```bash
   napari-mcp-install list
   ```

3. **Check permissions:**
   ```bash
   # macOS - Claude Desktop example
   ls -la ~/Library/Application\ Support/Claude/

   # Fix if needed
   chmod 755 ~/Library/Application\ Support/Claude/
   ```

4. **Create directory manually:**
   ```bash
   # macOS - Claude Desktop
   mkdir -p ~/Library/Application\ Support/Claude

   # Linux - Claude Desktop
   mkdir -p ~/.config/Claude

   # Then retry
   napari-mcp-install install claude-desktop
   ```

!!! failure "Config exists but server not configured" Problem: Config file exists but napari-mcp entry is missing.

**Solution:**
```bash
# Check current status
napari-mcp-install list

# Force reinstall
napari-mcp-install install <app> --force

# Or manually check/edit config
cat ~/.config/Claude/claude_desktop_config.json
```

Permission Errors

!!! failure "Permission denied writing config" Problem: Can't write to configuration file.

**Solutions:**
```bash
# Check file permissions
napari-mcp-install list  # Shows config paths

# Fix permissions (macOS/Linux)
chmod 644 <config-file-path>

# Check directory permissions
ls -la <directory-path>
chmod 755 <directory-path>
```

Python Environment Issues

!!! failure "napari-mcp not found in Python environment" Problem: Using --persistent but napari-mcp isn't installed in that environment.

**Solutions:**
```bash
# Check which Python
which python

# Install in current environment
pip install napari-mcp

# Then configure
napari-mcp-install install <app> --persistent

# Or specify exact Python path
napari-mcp-install install <app> --python-path /full/path/to/python
```

Verification Commands

# List all installations and their status
napari-mcp-install list

# Preview what would be installed
napari-mcp-install install <app> --dry-run

# Check installer version
napari-mcp-install --version

# Get help
napari-mcp-install --help
napari-mcp-install install --help

🚨 Common Setup Issues

Server Won't Start

!!! failure "uv: command not found" Problem: The uv command isn't found when trying to run the server.

**Solution:**
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart terminal or reload shell
source ~/.bashrc  # or ~/.zshrc
```

!!! failure "napari-mcp: command not found" Problem: Traditional installation command not found.

**Solutions:**
```bash
# Reinstall in development mode
pip install -e . --force-reinstall

# Or use Python module directly
python -m napari_mcp.server

# Check if it's in your PATH
which napari-mcp
```

!!! failure "Permission denied" Problem: File permission errors when running downloaded script.

**Solution:**
```bash
# Reinstall the package
pip install --force-reinstall napari-mcp

# Or run with Python module directly
python -m napari_mcp.server
```

Napari GUI Issues

!!! failure "Qt platform plugin not found" Problem: qt.qpa.plugin: Could not find the Qt platform plugin

**Solutions:**
```bash
# For headless/remote systems
export QT_QPA_PLATFORM=offscreen

# For Linux with X11
export QT_QPA_PLATFORM=xcb

# For debugging
export QT_DEBUG_PLUGINS=1
```

!!! failure "Napari window doesn't appear" Problem: Server starts but no napari window shows.

**Diagnosis:**
```bash
# Check display connection (Linux/macOS)
echo $DISPLAY

# Test basic Qt
python -c "from qtpy.QtWidgets import QApplication; app = QApplication([]); print('Qt works')"

# Test napari
python -c "import napari; viewer = napari.Viewer(); print('Napari works')"
```

**Solutions:**
- **Remote systems:** Enable X11 forwarding or use offscreen mode
- **macOS:** Check System Preferences > Security & Privacy
- **Windows:** Ensure graphics drivers are updated

!!! failure "Import errors with napari" Problem: ImportError: No module named 'napari'

**Solution:**
```bash
# Check napari installation
pip list | grep napari

# Reinstall napari
pip install --upgrade napari[all]

# Or with uv
uv pip install napari[all]
```

🔌 AI Assistant Connection Issues

Claude Desktop

!!! failure "Claude can't see napari tools" Problem: MCP tools don't appear in Claude Desktop.

**Checklist:**
1. **Config file location correct?**
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

2. **JSON syntax valid?**
   ```bash
   # Validate JSON
   cat claude_desktop_config.json | python -m json.tool
   ```

3. **File paths absolute?**
   ```json
   // Wrong - missing package specifier
   "args": ["run", "napari-mcp"]

   // Correct - full uv invocation
   "args": ["run", "--with", "napari-mcp", "napari-mcp"]
   ```

4. **Claude Desktop restarted?**
   - Completely quit and restart Claude Desktop
   - Check for error messages in console

!!! failure "MCP server connection failed" Problem: Claude shows connection errors.

**Debug steps:**
```bash
# Test server starts manually
napari-mcp

# Or via uv
uv run --with napari-mcp napari-mcp

# Check for error messages in verbose mode
MCP_LOG_LEVEL=DEBUG napari-mcp
```

Cursor & Claude Code

!!! failure "CLI installer failed" Problem: napari-mcp-install command fails.

**Solutions:**
```bash
# Reinstall napari-mcp
pip install --upgrade napari-mcp

# Check installation
napari-mcp-install --version

# Manual installation for a specific app
napari-mcp-install install cursor
```

!!! failure "Server not appearing in IDE" Problem: Installed server doesn't show up in Cursor/Claude Code.

**Debug:**
```bash
# Check current installations
napari-mcp-install list

# Force reinstall for specific IDE
napari-mcp-install install cursor --force
```

📦 Dependency Issues

Package Installation Problems

!!! failure "Package conflicts" Problem: Version conflicts between dependencies.

**Solution:**
```bash
# Use virtual environment
python -m venv fresh-env
source fresh-env/bin/activate
pip install -e .

# Or use uv with specific versions
uv run --with "napari>=0.5.5" --with "PyQt6>=6.5.0" --with napari-mcp napari-mcp
```

!!! failure "Qt backend conflicts" Problem: Multiple Qt installations causing issues.

**Diagnosis:**
```python
import qtpy
print(f"Using Qt API: {qtpy.API}")
print(f"Qt version: {qtpy.QT_VERSION}")
```

**Solution:**
```bash
# Force specific Qt backend
export QT_API=pyqt6

# Or reinstall clean
pip uninstall PyQt5 PyQt6 PySide2 PySide6
pip install PyQt6
```

Network and Firewall

!!! failure "Connection timeouts" Problem: Network timeouts when downloading dependencies.

**Solutions:**
```bash
# Increase timeout
pip install --timeout=60 napari

# Use different index
pip install -i https://pypi.python.org/simple/ napari

# Check proxy settings
pip install --proxy http://proxy:port napari
```

🔧 Performance Issues

Slow Startup

!!! failure "Server takes long to start" Problem: 30+ seconds to start server.

**Optimizations:**
```bash
# Pre-warm uv cache
uv run --with napari --help

# Use local installation
pip install -e .
napari-mcp  # Faster than uv run

# Check startup time
time uv run --with napari-mcp napari-mcp
```

Memory Issues

!!! failure "High memory usage" Problem: Excessive memory consumption.

**Monitoring:**
```bash
# Monitor memory usage
ps aux | grep napari

# Python memory profiling
python -m memory_profiler -m napari_mcp.server
```

**Solutions:**
- Close unused napari viewers
- Reduce image resolution for testing
- Use `gc.collect()` in custom code
- Monitor for memory leaks in long-running sessions

🖥️ Platform-Specific Issues

macOS

!!! failure "Gatekeeper blocks execution" Problem: "Cannot be opened because the developer cannot be verified"

**Solution:**
```bash
# If installed via pip, this shouldn't occur.
# For uv-cached files, try:
pip install --force-reinstall napari-mcp

# Or allow in System Preferences > Security & Privacy
```

!!! failure "Rosetta compatibility (Apple Silicon)" Problem: Performance issues on M1/M2 Macs.

**Solution:**
```bash
# Use native ARM Python
/opt/homebrew/bin/python3 -m pip install napari

# Check architecture
python -c "import platform; print(platform.machine())"
```

Windows

!!! failure "PowerShell execution policy" Problem: Scripts blocked by execution policy.

**Solution:**
```powershell
# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run directly
python -m napari_mcp.server
```

!!! failure "Path length limitations" Problem: File paths too long on Windows.

**Solution:**
- Enable long path support in Windows
- Use shorter directory names
- Move project closer to root drive

Linux

!!! failure "Display server issues" Problem: GUI doesn't work on headless systems.

**Solutions:**
```bash
# Virtual display
sudo apt-get install xvfb
xvfb-run -a napari-mcp

# Or use offscreen
export QT_QPA_PLATFORM=offscreen
```

🐛 Debugging Tools

Logging and Debug Output

# Enable verbose logging
export MCP_LOG_LEVEL=DEBUG

# Run with debug output
napari-mcp

# Or via Python module directly
python -u -m napari_mcp.server  # Unbuffered output

Testing Commands

# Test napari import
python -c "import napari; print('✅ napari works')"

# Test FastMCP
python -c "import fastmcp; print('✅ FastMCP works')"

# Test Qt
python -c "from qtpy.QtWidgets import QApplication; app = QApplication([]); print('✅ Qt works')"

# Full integration test
python -c "
import napari
import fastmcp
viewer = napari.Viewer()
print('✅ Full integration works')
viewer.close()
"

System Information

# Collect system info for bug reports
echo "=== System Information ==="
python --version
pip --version
uv --version
echo "Platform: $(python -c 'import platform; print(platform.platform())')"
echo "Qt API: $(python -c 'import qtpy; print(qtpy.API)')"
echo "Napari: $(python -c 'import napari; print(napari.__version__)')"
echo "FastMCP: $(python -c 'import fastmcp; print(fastmcp.__version__)')"

🆘 Getting Help

If you've tried all the solutions above and still have issues:

Before Asking for Help

Collect information:
- Error messages (full traceback)
- System information (OS, Python version)
- Steps to reproduce the issue
- What you've tried already

Create minimal example:

# Simplest possible test
python -c "import napari; viewer = napari.Viewer()"

Check existing issues:
- Search GitHub Issues
- Check napari and FastMCP issue trackers

Where to Get Help

GitHub Issues: Report bugs and ask questions
Discussions: Community discussions
Napari Community: Napari forum

Issue Template

When reporting bugs, please include:

## Bug Description
Brief description of the issue

## Steps to Reproduce
1. First step
2. Second step
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens (include full error messages)

## Environment
- OS: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
- Python: [e.g., 3.11.5]
- Napari: [e.g., 0.5.5]
- Installation method: [Zero install, traditional, etc.]

## Additional Context
Any other relevant information

Still stuck? Don't hesitate to ask for help! The community is here to support you. 🤝

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting

🛠️ CLI Installer Issues

Installation Problems

Configuration Issues

Permission Errors

Python Environment Issues

Verification Commands

🚨 Common Setup Issues

Server Won't Start

Napari GUI Issues

🔌 AI Assistant Connection Issues

Claude Desktop

Cursor & Claude Code

📦 Dependency Issues

Package Installation Problems

Network and Firewall

🔧 Performance Issues

Slow Startup

Memory Issues

🖥️ Platform-Specific Issues

macOS

Windows

Linux

🐛 Debugging Tools

Logging and Debug Output

Testing Commands

System Information

🆘 Getting Help

Before Asking for Help

Where to Get Help

Issue Template

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting

🛠️ CLI Installer Issues

Installation Problems

Configuration Issues

Permission Errors

Python Environment Issues

Verification Commands

🚨 Common Setup Issues

Server Won't Start

Napari GUI Issues

🔌 AI Assistant Connection Issues

Claude Desktop

Cursor & Claude Code

📦 Dependency Issues

Package Installation Problems

Network and Firewall

🔧 Performance Issues

Slow Startup

Memory Issues

🖥️ Platform-Specific Issues

macOS

Windows

Linux

🐛 Debugging Tools

Logging and Debug Output

Testing Commands

System Information

🆘 Getting Help

Before Asking for Help

Where to Get Help

Issue Template