Skip to content

Troubleshooting

Common issues and their solutions.

Installation Issues

uv: command not found

Problem: The uv command is not recognized.

Solution: Install uv by following the uv installation guide:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation Takes Too Long

Problem: Installation seems stuck or takes forever.

Solution: This is normal! The first installation downloads many dependencies. Be patient: - First install: 1-2 minutes - Documentation indexing: 5-10 minutes - Subsequent operations are much faster

Python Version Error

Problem: Error about Python version.

Solution: HoloViz MCP requires Python 3.11 or newer. Check your version:

python --version

Install a newer Python version if needed.

Server Issues

Server Won't Start

Problem: MCP server fails to start.

Solution:

  1. Test the server directly:
holoviz-mcp

  1. Check for error messages in the output

  2. Verify Python version:

python --version  # Should be 3.11+
  1. Reinstall HoloViz MCP:
uv tool uninstall holoviz-mcp
uv tool install holoviz-mcp

Server Crashes

Problem: Server starts but crashes during use.

Solution:

  1. Check logs (VS Code: Output → MCP: holoviz)

  2. Try running with debug logging:

HOLOVIZ_MCP_LOG_LEVEL=DEBUG holoviz-mcp
  1. Report the issue on GitHub with logs

Port Already in Use (HTTP Mode)

Problem: Error: bind: address already in use

Solution:

Find what's using port 8000: 

lsof -i :8000

Use a different port: 

HOLOVIZ_MCP_PORT=8001 HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp

Documentation Issues

AI Assistant Doesn't Recognize Components

Problem: AI provides generic responses, not Panel-specific information.

Solution:

  1. Verify documentation index exists:
ls ~/.holoviz-mcp
  1. Create or recreate the index:
holoviz-mcp update index

  1. Wait for indexing to complete (5-10 minutes)

  2. Restart your IDE

  3. Test with a specific query:

What parameters does Panel's TextInput component have?

Documentation Index Creation Fails

Problem: holoviz-mcp update index fails or times out.

Solution:

  1. Check internet connection

  2. Try again with debug logging:

HOLOVIZ_MCP_LOG_LEVEL=DEBUG holoviz-mcp update index
  1. Clear existing data and retry:
rm -rf ~/.holoviz-mcp/vector_db
holoviz-mcp update index
  1. Check GitHub API rate limits (wait an hour and retry)

Documentation Seems Outdated

Problem: AI provides outdated information.

Solution: Update the documentation index:

holoviz-mcp update index

IDE Integration Issues

VS Code Not Detecting Server

Problem: MCP server doesn't appear in VS Code.

Solution:

  1. Verify configuration file location:

  2. Command Palette → "MCP: Edit Settings"

  3. Check configuration syntax:

{
  "servers": {
    "holoviz": {
      "type": "stdio",
      "command": "holoviz-mcp"
    }
  },
  "inputs": []
}

  1. Restart VS Code completely

  2. Check Output panel: View → Output → MCP: holoviz

Claude Desktop Not Connecting

Problem: MCP server doesn't connect to Claude Desktop.

Solution:

  1. Verify configuration file location:
  2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  3. Windows: %APPDATA%\Claude\claude_desktop_config.json

  4. Check JSON syntax is valid

  5. Restart Claude Desktop completely

  6. Look for MCP indicator (🔌) in the interface

Remote Development Not Working

Problem: MCP server doesn't work in remote SSH/Dev Containers.

Solution:

  1. Use Workspace or Remote mcp.json, not User settings

  2. Ensure uv and Python are installed in the remote environment

  3. Consider using HTTP transport:

{
  "servers": {
    "holoviz": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp/"
    }
  }
}

Then start server in remote:

HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp

Docker Issues

Docker Container Won't Start

Problem: Container exits immediately.

Solution:

  1. Check logs:
docker logs holoviz-mcp
  1. Verify port availability:
lsof -i :8000
  1. Try with debug logging:
docker run -it --rm \
  -e HOLOVIZ_MCP_LOG_LEVEL=DEBUG \
  -v ~/.holoviz-mcp:/root/.holoviz-mcp \
  ghcr.io/marcskovmadsen/holoviz-mcp:latest

Documentation Not Persisting in Docker

Problem: Documentation reindexes every time container restarts.

Solution: Ensure volume is mounted:

docker run -v ~/.holoviz-mcp:/root/.holoviz-mcp ...

Verify:

docker inspect holoviz-mcp | grep -A 10 Mounts

Permission Errors in Docker

Problem: Permission denied when accessing mounted volumes.

Solution:

Linux: Adjust ownership: 

sudo chown -R $USER:$USER ~/.holoviz-mcp

Or run with specific user:

docker run --user $(id -u):$(id -g) ...

Performance Issues

Slow Responses

Problem: AI takes a long time to respond to queries.

Solution:

  1. First query after startup is slower (initializing)

  2. Subsequent queries should be fast

  3. If consistently slow, check system resources

  4. Consider recreating documentation index:

rm -rf ~/.holoviz-mcp/vector_db
holoviz-mcp update index

High Memory Usage

Problem: HoloViz MCP uses too much memory.

Solution:

  1. This is expected with large documentation indices

  2. For Docker, set memory limits:

docker run --memory=2g ...
  1. Restart the server periodically if needed

Getting Help

Check Logs

VS Code: View → Output → MCP: holoviz

Command Line:

HOLOVIZ_MCP_LOG_LEVEL=DEBUG holoviz-mcp

Docker:

docker logs holoviz-mcp

Report an Issue

If you can't resolve the issue:

  1. Gather information:
  2. Python version: python --version
  3. HoloViz MCP version: holoviz-mcp --version
  4. Operating system
  5. Error messages and logs
  6. Report on GitHub Issues
  7. Include:
  8. Clear description of the problem
  9. Steps to reproduce
  10. Error messages and logs
  11. What you've tried

Community Support

Next Steps