# Troubleshooting Guide

## Common Issues

### Qdrant 404 Not Found on Search
**Symptoms:**
- `POST /v1/search/` returns `503 Service Unavailable`.
- Logs show `qdrant_client.http.exceptions.UnexpectedResponse: ... 404 Not Found`.
- `repro_qdrant.py` fails on `query_points`.

**Cause:**
- Version mismatch between `qdrant-client` (Python library) and Qdrant Server.
- `qdrant-client >= 1.16.x` uses the new `query_points` API.
- Older Qdrant servers (e.g., `v1.7.4`) do not support this endpoint.

**Solution:**
Upgrade Qdrant Server to `v1.13.0` or newer.
Update your `docker-compose.yml`:
```yaml
services:
  qdrant:
    image: qdrant/qdrant:v1.13.0
```

### ModuleNotFoundError in Tests
**Symptoms:**
- `pytest` fails with `ModuleNotFoundError: No module named 'src'`.

**Cause:**
- `PYTHONPATH` is not set to include the package root or `src` directory.

**Solution:**
Run pytest with `PYTHONPATH` explicitly set:
```bash
export PYTHONPATH=$PYTHONPATH:$(pwd)/src && pytest
```
