# NautheraCacheErrors

More than 1% of nauthera-server cache operations fail.

## Meaning

For ten minutes, more than the threshold (1%) of `nauthera_cache_operations_total` have
had `result="error"`, without the cache necessarily being down. Causes include timeouts
(`cache.read_timeout`, `write_timeout`, 3s), an exhausted connection pool
(`cache.pool_size`, 10), a Redis that refuses writes (out of memory, read-only), and
`cache.replica_acks` waiting on a replica that is gone.

## Impact

Each failed operation refuses one authorization code, refresh token, DPoP proof or
pushed request, so some relying parties' sign-ins and refreshes fail at random. Failed
throttle reads let some sign-in attempts through unthrottled.

## Diagnosis

1. Which operations fail: `sum by (op)
   (rate(nauthera_cache_operations_total\{job="<name>",result="error"\}[5m]))`.
2. Latency: `histogram_quantile(0.99, sum by (op, le)
   (rate(nauthera_cache_operation_seconds_bucket\{job="<name>"\}[5m])))`. Latency near the
   timeouts means a slow or overloaded Redis.
3. Check NautheraCacheUnavailable: a full outage window opens once failures persist.
4. Redis side, with its owner: `INFO memory`, `INFO replication`, slow log, CPU, and
   whether a failover happened.

## Mitigation

- Slow or overloaded Redis: scale it or move other workloads off it.
- Pool exhaustion under load: raise `config.cache.pool_size`.
- Out of memory: raise `maxmemory`; never turn on eviction.
- `replica_acks` with a missing replica: restore the replica, or lower
  `config.cache.replica_acks` below the number of healthy replicas.

## Escalation

Escalate to the cache owner when Redis is slow or erroring. If Redis is healthy and only
the server's operations fail, open an issue with the failing `op` values, the error lines
from the server log and the `cache.*` settings (without passwords).

---

[Alert runbooks](https://www.nauthera.io/docs/v1/runbooks/alerts) · Generated from [`internal/runbook/alerts.yaml`](https://github.com/nauthera/nauthera-server/blob/main/internal/runbook/alerts.yaml) and [`operator/internal/runbook/alerts.yaml`](https://github.com/nauthera/nauthera-server/blob/main/operator/internal/runbook/alerts.yaml) in nauthera-server.