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.

Eligibility and missing configuration

In a host that registers this check, CanRun remains true without a global connection string because the tenant catalog may supply tenant-specific configuration. The Doctor executor must reach RunAsync to resolve that configuration. Eligibility is not a health result: missing or blank configuration returns skip with Valkey/Redis not configured and candidate-key evidence before opening a socket.

With two or more cataloged tenants, each tenant receives its own result. A configured tenant receives the actual RESP handshake verdict; an unconfigured tenant retains skip in aggregate evidence. Any tenant failure fails the aggregate. With no catalog, an empty catalog or one cataloged tenant, the existing single-run behavior applies. This library contract does not assert that a particular deployed host has registered the check.

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

The eligibility and missing-configuration contract was verified against 978c150ccf by the complete ServiceGraph project (PCD-367). Recheck the library and executor behavior:

pwsh -NoProfile -File tools/scripts/test-targeted-xunit.ps1 -Project src/__Libraries/__Tests/StellaOps.Doctor.Plugins.ServiceGraph.Tests/StellaOps.Doctor.Plugins.ServiceGraph.Tests.csproj -All -BuildProjectReferences -Restore

In a host that registers the check, inspect the configured dependency with:

stella doctor run --check check.servicegraph.valkey