> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common issues with CodeAlive

## Quick Diagnostics

Run these commands to quickly identify where the problem is:

**Test your API key:**

```bash theme={null}
curl -s -o /dev/null -w "%{http_code}" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://app.codealive.ai/api/tools/get_data_sources
```

Expected: `200`. If you get `401`, your API key is invalid or expired.

**Test remote MCP server:**

```bash theme={null}
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:**

```bash theme={null}
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):**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://app.codealive.ai/api/tools/get_data_sources
```

Expected: a JSON array of your indexed repositories.

## FAQ and common issues

<AccordionGroup>
  <Accordion title="What files does CodeAlive index, and how can I exclude files?">
    CodeAlive indexes source code, configuration, documentation, and other supported text-based files. It respects `.gitignore` and automatically removes common low-value content such as vendored dependencies, minified assets, and source maps. Binary or unsupported formats are skipped.

    For tracked, project-specific content that should not appear in CodeAlive search, add its paths or patterns to `.codealiveignore` using `.gitignore` syntax. See [Prepare your repository](/code-preparation) for the supported-file rules and realistic examples.
  </Accordion>

  <Accordion title="Repository not indexing">
    **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
  </Accordion>

  <Accordion title="API key not working">
    **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. Make sure at least one repository has been added to your organization before creating the key
    3. Generate a new key in the dashboard under **MCP & API** → **+ Create API Key**
    4. Check for extra whitespace or line breaks when copying the key
    5. Ensure the key hasn't been revoked — only active keys work
    6. Test with curl:
       ```bash theme={null}
       curl -H "Authorization: Bearer YOUR_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{}' \
         https://app.codealive.ai/api/tools/get_data_sources
       ```
  </Accordion>

  <Accordion title="MCP server not connecting">
    **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`
  </Accordion>

  <Accordion title="Agent not detecting CodeAlive tools">
    **Symptoms:** AI agent doesn't use `semantic_search` / `grep_search` / `chat`, 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](/integrations/mcp))
    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
  </Accordion>

  <Accordion title="Slow responses">
    **Symptoms:** Queries take a long time or timeout.

    **Solutions:**

    1. Use more specific queries — broad searches across large codebases take longer
    2. Use `semantic_search` or `grep_search` instead of `chat` 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:
       ```bash theme={null}
       docker run -d -p 8000:8000 \
         -e CODEALIVE_API_KEY=YOUR_API_KEY \
         ghcr.io/codealive-ai/codealive-mcp:main
       ```
  </Accordion>

  <Accordion title="Docker container won't start">
    **Symptoms:** Container exits immediately, port conflicts, image pull failures.

    **Solutions:**

    1. **Port conflict:** Check if port 8000 is already in use:
       ```bash theme={null}
       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`:
       ```bash theme={null}
       docker pull ghcr.io/codealive-ai/codealive-mcp:main
       ```
    4. **Check logs:** `docker logs codealive-mcp` for specific error messages
  </Accordion>

  <Accordion title="'Tool not found' errors">
    **Symptoms:** Agent reports that `semantic_search`, `grep_search`, `chat`, 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: `semantic_search`, `grep_search`, `chat`, `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
  </Accordion>

  <Accordion title="Search returns irrelevant results">
    **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 `semantic_search` for architecture-level or intent-based queries
    4. Try `grep_search` for exact function/class names, log lines, or regex lookups
    5. Check that the repository index is up to date in the dashboard
  </Accordion>
</AccordionGroup>

## Getting Help

<CardGroup cols={3}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/CodeAlive-AI/codealive-mcp/issues">
    Report bugs and request features
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@codealive.ai">
    Contact the CodeAlive team directly
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the full documentation
  </Card>
</CardGroup>