Skip to main content

​
Quick Diagnostics

Run these commands to quickly identify where the problem is: Test your API key: 
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.codealive.ai/api/datasources/alive
Expected: 200. If you get 401, your API key is invalid or expired. Test remote MCP server: 
curl -s -o /dev/null -w "%{http_code}" https://mcp.codealive.ai/api/
Expected: 200 or 405. If the connection times out, check your network/firewall. Test local Docker container: 
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/
Expected: 200 or 405. If connection refused, the container isn’t running. List your data sources (verify repos are indexed): 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.codealive.ai/api/datasources/all
Expected: a JSON array of your indexed repositories.

​
Common Issues

Symptoms: Repository appears in dashboard but shows no indexed content, or indexing seems stuck.Solutions:
  1. Check that the repository is not empty and contains code files
  2. Verify your GitHub/GitLab/Bitbucket connection is still authorized
  3. Check repository permissions — CodeAlive needs read access
  4. For large repositories, initial indexing can take 15+ minutes — check the status indicator in the dashboard
  5. Try removing and re-adding the repository
Symptoms: 401 Unauthorized responses, “invalid API key” errors.Solutions:
  1. Verify the key format — it should be passed as Bearer YOUR_KEY in the Authorization header
  2. Generate a new key in the dashboard under MCP & API → + Create API Key
  3. Check for extra whitespace or line breaks when copying the key
  4. Ensure the key hasn’t been revoked — only active keys work
  5. Test with curl: 
    curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.codealive.ai/api/datasources/alive
Symptoms: Agent can’t find CodeAlive tools, connection errors, timeouts.Solutions:
  1. Verify the URL is exactly https://mcp.codealive.ai/api/ (trailing slash matters for some agents)
  2. Check your network — some corporate firewalls block MCP connections
  3. Restart your AI agent after changing MCP configuration
  4. For Docker: ensure the container is running with docker ps
  5. For Docker: verify port mapping — default is 8000:8000
Symptoms: AI agent doesn’t use codebase_search / codebase_consultant, says tools aren’t available.Solutions:
  1. Restart your AI agent — most agents only load MCP config at startup
  2. Check config file syntax — a missing comma or bracket breaks the whole file
  3. Verify the config file is in the right location (varies by agent — see integration guides)
  4. In Cursor: check Settings → Features → MCP for server status
  5. In VS Code: check Output → MCP panel for connection errors
  6. In Claude Code: run claude mcp list to verify the server is registered
Symptoms: Queries take a long time or timeout.Solutions:
  1. Use more specific queries — broad searches across large codebases take longer
  2. Use codebase_search instead of codebase_consultant for simple lookups
  3. Scope searches to specific repositories instead of searching everything
  4. For remote MCP: check your network latency to mcp.codealive.ai
  5. Consider running Docker locally for lower latency: 
    docker run -d -p 8000:8000 \
  -e CODEALIVE_API_KEY=YOUR_API_KEY \
  ghcr.io/codealive-ai/codealive-mcp:main
Symptoms: Container exits immediately, port conflicts, image pull failures.Solutions:
  1. Port conflict: Check if port 8000 is already in use: 
    lsof -i :8000
    Use a different port: -p 9000:8000
  2. API key not set: The container requires CODEALIVE_API_KEY environment variable
  3. Image pull failure: Ensure you can access ghcr.io: 
    docker pull ghcr.io/codealive-ai/codealive-mcp:main
  4. Check logs: docker logs codealive-mcp for specific error messages
Symptoms: Agent reports that codebase_search, codebase_consultant, or get_data_sources is not available.Solutions:
  1. Verify MCP is enabled in your agent — some agents require explicit opt-in
  2. Check that the tool names are exact: codebase_search, codebase_consultant, get_data_sources
  3. Ensure the MCP server is connected (see “MCP server not connecting” above)
  4. Some agents cache tool lists — restart the agent to refresh
Symptoms: Search results don’t match your query, too many results from wrong files.Solutions:
  1. Use more specific terms — include class names, function names, or module names
  2. Scope the search to a specific repository if you have multiple indexed
  3. Try deep search mode for architectural questions
  4. Try fast search mode for exact function/class name lookups
  5. Check that the repository index is up to date in the dashboard

​
Getting Help

GitHub Issues

Report bugs and request features

Email Support

Contact the CodeAlive team directly

Documentation

Browse the full documentation