Troubleshooting

Diagnosing common container socket errors, provider timeouts, and permissions.

Troubleshooting & FAQ

Common diagnostic solutions and answers to frequent questions.

1. Container Socket Not Found

Symptom: Error: Could not connect to Podman/Docker socket

Solution:

• Podman: Ensure the user socket is running:

  systemctl --user enable --now podman.socket
  export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"

• Docker: Ensure Docker Desktop or dockerd is running and your user can access its socket.
• NIKI probes rootless Podman first, then rootful Podman and Docker; rootless operation is not guaranteed.

2. Spend Cap Exceeded Mid-Run

Symptom: Error: Spend cap exceeded ($2.50 USD ceiling reached)

Solution:

• Increase general.spend_cap_usd in niki.toml.
• Switch high-frequency stages (like agents.tester) to more cost-effective models such as gpt-4o-mini or the haiku alias.

3. Rate Limit Errors (HTTP 429)

Symptom: Error: Provider rate limit exceeded

Solution:

• Define fallbacks = ["provider-slug", ...] for the agent role in niki.toml.
• NIKI already uses bounded exponential backoff with jitter for retryable provider responses; those delays are not user-configurable in niki.toml.