Skip to main content

Troubleshooting

Low cache hit rate​

Check:

aif_cache_exact_hits
aif_cache_semantic_hits
aif_cache_misses
aif_semantic_threshold_results_total{result="fail"}

Common causes: threshold too high, prompts not similar, semantic cache disabled, retention too short.

Redis connection failure​

Docker Compose:

redis_url redis://redis:6379;

Local source run:

redis_url redis://127.0.0.1:6379;

Qdrant connection failure​

Docker Compose:

qdrant_url http://qdrant:6334;

Local source run:

qdrant_url http://127.0.0.1:6334;

Qdrant vector size mismatch​

Fix by recreating the collection, using a matching embedding model, or updating qdrant_vector_size.

ai-firewall: command not found​

After source build, use:

./target/release/ai-firewall

Or install it:

sudo install -m 0755 target/release/ai-firewall /usr/local/bin/ai-firewall

/metrics shows one in-flight request​

This is normal because the metrics request itself is active.