checkId: check.servicegraph.valkey plugin: stellaops.doctor.servicegraph severity: warn tags: [servicegraph, valkey, redis, cache]

Valkey/Redis Connectivity

This Doctor check helps operators confirm that Stella Ops can parse its cache connection string and reach the Valkey/Redis backend, so queue coordination and latency-sensitive features stay healthy.

What It Checks

Reads Valkey:ConnectionString, Redis:ConnectionString, ConnectionStrings:Valkey, ConnectionStrings:Redis, or the platform router key Router:Messaging:valkey:ConnectionString (compose Router__Messaging__valkey__ConnectionString), parses the host, port, and optional password=, and opens a TCP connection. The router key is what the standard deployment sets on every service, including doctor-web, so the check resolves on the real environment instead of silently skipping.

After the socket opens it performs a real Redis/Valkey RESP handshake (DOC-P0-002): it sends AUTH <password> (only when a password is configured) and PING, then reads the inline +PONG reply. This proves the cache is actually serving, not merely that a port is open — a wrong-port, half-open, or AUTH-rejecting (-NOAUTH / -WRONGPASS) instance now fails instead of passing. The password is never logged or echoed (it is redacted everywhere it could appear in evidence).

ConditionResult
No cache connection string configuredskip
Connection string parses, the target is reachable, and PING returns +PONGpass
Parsing fails, the target cannot be reached, or the AUTH/PING handshake failsfail

For cataloged tenants, tenant connection-string overrides under Doctor:TenantOverrides:<tenant>:<key> or Tenants:<tenant>:<key> are checked before global keys. Transient socket exceptions are retried with bounded ProbeRetry; returned invalid-config or failed-handshake results are not retried. Tenant fan-out evidence includes per-tenant severity and retry attempts.

Why It Matters

Cache unavailability affects queue coordination, state caching, and latency-sensitive platform features. A malformed connection string is also an early warning that the environment is not wired correctly.

Common Causes

How to Fix

Docker Compose

services:
  doctor-web:
    environment:
      Valkey__ConnectionString: valkey:6379,password=${STELLAOPS_VALKEY_PASSWORD}

docker compose -f devops/compose/docker-compose.stella-ops.yml ps valkey
docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web sh -lc "nc -zv valkey 6379"

Bare Metal / systemd

redis-cli -h <valkey-host> -p 6379 ping

Kubernetes / Helm

Use a cluster-local service name in the connection string and verify the port exposed by the StatefulSet or Service.

Verification

stella doctor run --check check.servicegraph.valkey