Troubleshooting#

Service Does 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 OpenVINO model server, 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 that .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 when running with the Docker Compose tool.
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 the Redis cache:
```
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 OpenVINO model server backend bypasses system proxy variables (trust_env=False) to avoid routing internal OpenVINO model server traffic through a corporate proxy. If your OpenVINO model server 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 the OpenVINO model server:
```
curl http://<ovms-host>:8000/v3/models
```

Normalization Differences: The ExactMatcher normalizes text (lowercase, whitespace trim, and 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 that 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 OpenVINO model server has high load, latency increases. Monitor OpenVINO model server 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.