Troubleshooting

Common Issues and Solutions

Quick fixes for common StrataRouter issues.

---

High Latency

Symptoms

• P99 latency > 50ms
• Slow response times

Diagnosis

# Enable profiling
result = executor.execute(query)
print(result.profile)

# Check metrics
GET /metrics

Solutions

1. Enable Caching

   config = RuntimeConfig(cache_enabled=True)
   

2. Reduce HNSW ef_search

   config = RouterConfig(hnsw_ef_search=30)
   

3. Check Provider Latency

   # Review provider metrics
   stratarouter_provider_latency_ms
   

---

Low Cache Hit Rate

Symptoms

• Hit rate < 70%
• High LLM costs

Solutions

1. Lower Similarity Threshold

   config = RuntimeConfig(cache_similarity_threshold=0.90)
   

2. Increase Cache Size

   config = RuntimeConfig(cache_max_size=50000)
   

3. Extend TTL

   config = RuntimeConfig(cache_ttl=7200)  # 2 hours
   

---

Routing Errors

Low Confidence Scores

Cause: Route descriptions too similar

Fix:

# Make routes more distinct
router.add_route(Route(
    "billing_payments",
    "Credit card payments, invoices, refunds, billing cycles"
))

router.add_route(Route(
    "technical_support",
    "Software bugs, crashes, errors, technical troubleshooting"
))

No Route Found

Cause: Threshold too high

Fix:

config = RouterConfig(threshold=0.4)  # Lower threshold

---

Memory Issues

High Memory Usage

Diagnosis:

# Check memory metrics
stratarouter_memory_bytes

Solutions:

1. Reduce HNSW M Parameter

   config = RouterConfig(hnsw_m=8)
   

2. Limit Cache Size

   config = RuntimeConfig(cache_max_size=10000)
   

3. Use Redis for Cache

   config = RuntimeConfig(cache_backend="redis")
   

---

Connection Issues

Provider Timeouts

Symptoms: Frequent timeout errors

Fix:

config = RuntimeConfig(
    provider_timeout_ms=30000,  # 30 seconds
    retry_max_attempts=3
)

Database Connection Pool Exhausted

Fix:

config = RuntimeConfig(
    db_pool_size=50,
    db_max_overflow=20
)

---

Performance Degradation

Gradual Slowdown

Diagnosis:

# Check metrics over time
rate(stratarouter_routing_latency_ms[1h])

Common Causes: - Cache eviction thrashing - Memory pressure - Too many routes - Provider rate limits

Fix:

# Monitor and adjust
config = RuntimeConfig(
    cache_max_size=20000,  # Increase
    rate_limit_per_second=5000  # Adjust
)

---

Integration Issues

LangChain Integration

Error: ImportError: No module named stratarouter.integrations

Fix:

pip install --upgrade stratarouter[langchain]

Embedding Dimension Mismatch

Error: DimensionMismatchError

Fix:

# Match router dimension to embedding model
router = Router(dimension=384)  # all-MiniLM-L6-v2
router = Router(dimension=768)  # all-mpnet-base-v2
router = Router(dimension=1536)  # OpenAI text-embedding-ada-002

---

Diagnostic Commands

Check Status

GET /health/ready

View Metrics

curl localhost:9090/metrics

Check Logs

tail -f /var/log/stratarouter/stratarouter.log

Test Route

from stratarouter.testing import test_route

result = test_route(
    router=router,
    query="I need help with payment",
    expected_route="billing"
)

print(f"Matched: {result.matched}")
print(f"Confidence: {result.confidence}")

---

Debug Mode

Enable Verbose Logging

import logging

config = RuntimeConfig(
    log_level=logging.DEBUG,
    log_format="json"
)

---

Common Error Codes

Code	Meaning	Solution
400	Invalid request	Check query format
401	Unauthorized	Verify API key
429	Rate limited	Reduce request rate
500	Internal error	Check logs
503	Service unavailable	Check health endpoint

---

Getting Help

Before Asking

1. Check logs
2. Review metrics
3. Test in isolation
4. Reproduce issue

Where to Ask

• Discord
• GitHub Issues
• Discussions

---

Next Steps

Monitoring

Set up observability

Monitoring Guide →

Performance

Optimize your deployment

Tuning Guide →