# Troubleshooting

> Common issues and solutions for the MarketCheck MCP Server — server startup, connection problems, API errors, and data quality.

Quick solutions for the most common issues when running the MarketCheck MCP Server.



## Server Won't Start

| Symptom  | Cause    | Solution |
|----------|----------|----------|
| `ModuleNotFoundError` | Dependencies not installed | Run `uv sync` or `pip install -e .` |
| Python version error | Python < 3.12 | Install Python 3.12+ |
| Import errors | Corrupted environment | Delete `.venv/` and run `uv sync` again |




## Connection Issues

| Symptom  | Cause    | Solution |
|----------|----------|----------|
| Claude Desktop doesn't see the server | Config file error | Verify JSON syntax in `claude_desktop_config.json` and restart Claude Desktop |
| "Server not found" | Wrong path | Use absolute path to `server.py` in the configuration |
| HTTP mode not connecting | Port in use | Change port with `--port 8001` or stop the conflicting process |
| Hosted server not responding | Network or key issue | Verify your API key is active and test with `curl "https://api.marketcheck.com/mcp?api_key=YOUR_KEY"` |




## API and Data Errors

| Symptom  | Cause    | Solution |
|----------|----------|----------|
| 401 Unauthorized | Invalid API key | Verify `MARKETCHECK_API_KEY` is set correctly |
| Empty search results | Mismatched filter values | Run a facets query first to discover exact valid values |
| 429 Too Many Requests | Rate limit exceeded | Implement backoff between calls; contact support for tier upgrade |
| Timeout errors | Large result set or slow network | Reduce `rows`, add more filters, or increase timeout in client |




## Data Quality

| Symptom  | Cause    | Solution |
|----------|----------|----------|
| Missing fields in response | Token optimization | Set `include_dealer_object=true` or `include_build_object=true` as needed |
| Only one photo per listing | Default behavior | Set `fetch_all_photos=true` for full photo arrays |
| Type validation errors | LLM sending strings for numbers | The server handles this automatically; if persisting, report the specific tool and parameters |




## Debug Mode

Running the server with the `--debug` flag produces verbose logs that help diagnose issues:

```bash
python server.py --debug
```

Include relevant log output when contacting support.



## See Also

- [Getting Started](/docs/get-started/api/mcp/getting-started) — Installation and setup guide
- [Getting Support](/docs/get-started/api/getting-support) — Contact support and check system status