Troubleshooting#

Service Will Not Start#

Port Conflict: Confirm that port 8080 (API) or 9090 (metrics) is not already in use:
```
ss -ltnp | grep 8080
ss -ltnp | grep 9090
```
Missing VLM Variables: If DEFAULT_MATCHING_STRATEGY is semantic or hybrid, the service will log an error at startup if the required VLM variables are missing. Check startup logs:
```
make docker-logs
```
For OVMS, ensure OVMS_ENDPOINT and OVMS_MODEL_NAME are set in .env. For openvino_local, ensure OPENVINO_MODEL_PATH points to an accessible directory. For openai, ensure OPENAI_API_KEY is set.
Invalid .env: Verify .env exists and has no syntax errors. The service silently falls back to defaults for missing keys, but completely absent .env files will use all defaults — including an empty OVMS_ENDPOINT.

Docker run: Use make docker-logs or docker compose -f docker/docker-compose.yml ps to inspect startup errors.
Proxy blocks: If behind a corporate proxy, curl hitting localhost may be blocked. Add --noproxy '*':
```
curl --noproxy '*' http://localhost:8080/api/v1/health
```

Wrong Strategy: Check that DEFAULT_MATCHING_STRATEGY in .env is semantic or hybrid, not exact.
VLM Backend Unavailable: The health endpoint reports vlm_status. If it shows "unavailable", the backend is misconfigured or unreachable. Check OVMS_ENDPOINT connectivity from inside the container:
```
docker exec semantic-search-agent curl -s ${OVMS_ENDPOINT}/v3/models
```
Confidence Threshold Too High: If the VLM returns YES but matches are still rejected, the confidence score may be below CONFIDENCE_THRESHOLD (default 0.85). Lower the threshold or use the /compare/semantic endpoint to inspect raw responses.
Cache Stale: If you recently changed configuration but are getting cached results, clear the cache by restarting the service (in-memory cache) or flushing Redis:
```
docker exec semantic-redis redis-cli FLUSHDB
```

Wrong Endpoint Format: OVMS_ENDPOINT must be a full base URL without a trailing slash, e.g. http://ovms-host:8000. The service appends /v3/chat/completions automatically.
Proxy Interference: The OVMS backend bypasses system proxy variables (trust_env=False) to avoid routing internal OVMS traffic through a corporate proxy. If your OVMS server requires proxy access, set NO_PROXY or adjust the backend configuration.
Model Not Loaded: Confirm the model specified in OVMS_MODEL_NAME is actually loaded in OVMS:
```
curl http://<ovms-host>:8000/v3/models
```

Normalization Differences: The ExactMatcher normalizes text (lowercase, whitespace trim, special character removal) before comparison. Inputs like "Coca-Cola" and "coca cola" will match. If you expect case-sensitive behavior, set CONFIDENCE_THRESHOLD=1.0 and use the exact strategy only.
Quantity Mismatch Not Reported: Items with matching names but different quantities appear in validation.quantity_mismatch, not in validation.missing. Check both arrays in the response.
Items Appear in Both Missing and Extra: This indicates the names are semantically different from the service’s perspective. Use /compare/semantic to diagnose the VLM response directly for the specific pair.

Cache Disabled: Confirm CACHE_ENABLED=true in .env. Without caching, every unique pair triggers a VLM inference call.
OVMS Overloaded: If OVMS has high load, latency increases. Monitor OVMS metrics and consider increasing OVMS_TIMEOUT for slow responses.
Use Hybrid Strategy: With DEFAULT_MATCHING_STRATEGY=hybrid, exact matches are resolved without any VLM call, significantly reducing latency for items with consistent naming.