How it worksTrustFAQ

Troubleshooting

Common errors and fixes when integrating NjiraAI.

Connection errors

connection refused on port 8080

Cause: Gateway is not running.

# Fix: Start services
make up-all

# Verify:
curl -sf http://localhost:8080/health | jq .
# Expected: {"status": "ok"}

connection refused on port 50051

Cause: Intelligence service is not running.

# Fix: Start all services
make up-all

# Or start Intelligence alone:
make dev-intelligence

Authentication errors

401 Unauthorized

Cause: Invalid or missing API key.

# Fix: Seed dev API keys
make seed-redis-docker

# Verify key exists:
docker compose -f infra/docker-compose.yml exec redis redis-cli HGETALL api_keys

Check your request:

# API key must be in Authorization header:
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer nj_live_dev_key_12345" \
  ...

Key format: nj_live_* (production) or nj_test_* (test).

403 Forbidden (unexpected)

Cause: A policy is blocking your request.

# Check the response body for the reason:
curl -s http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer nj_live_dev_key_12345" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"your message"}]}' | jq .

Look at reason_code and reason fields. If it's a false positive:

  1. Switch to shadow mode (SHADOW_MODE=true) to unblock
  2. Adjust the policy pack rules
  3. Re-enable enforcement

Policy errors

Policies not loading

Cause: Intelligence service can't find YAML files.

# Default path: policies/ directory
# Override with POLICIES_DIR env var

# Check policy files exist:
ls policies/*/latest.yaml

# Check Intelligence logs:
docker compose -f infra/docker-compose.yml logs intelligence | tail -20

Policy changes not taking effect

Cause: Intelligence needs to be restarted to reload policies.

# Restart Intelligence:
docker compose -f infra/docker-compose.yml restart intelligence

# Or restart everything:
make up-all

Service health

Check all services

# Gateway health
curl -sf http://localhost:8080/health | jq .

# API health
curl -sf http://localhost:8081/health | jq .

# Docker service status
docker compose -f infra/docker-compose.yml ps

Expected output (all healthy)

NAME           STATUS
timescaledb    Up (healthy)
redis          Up (healthy)
intelligence   Up
gateway        Up
api            Up
console        Up

Intelligence returns errors

# Check Intelligence logs for Python errors:
docker compose -f infra/docker-compose.yml logs intelligence --tail 50

# Common causes:
# - Missing Python dependencies → rebuild: docker compose build intelligence
# - Invalid policy YAML → check syntax with: python -c "import yaml; yaml.safe_load(open('policies/pii_guard/latest.yaml'))"

Performance issues

High latency on verdicts

# Check X-Njira-Latency-Ms header:
curl -s -D - http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer nj_live_dev_key_12345" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}]}' \
  2>&1 | grep -i njira

Targets:

  • Pattern/regex rules: < 20ms
  • Hazmat scanner: < 100ms
  • Full pipeline: < 200ms

If latency is high, check Intelligence logs for slow evaluations.

Docker issues

Port conflicts

# Check what's using a port:
lsof -i :8080

# Stop conflicting services or change port in docker-compose.yml

Stale containers

# Full cleanup (preserves data):
docker compose -f infra/docker-compose.yml down
make up-all

# Nuclear reset (destroys data):
# make down-v  # WARNING: deletes volumes

Getting help