checkId: check.router.messaging.transport plugin: stellaops.doctor.servicegraph severity: fail tags: [router, messaging, transport, valkey, connectivity]

Router Messaging Transport

This Doctor check confirms the active Router messaging transport (the Valkey-backed async backbone) is reachable AND serving — distinct from both the Valkey cache and the Notify queue.

What It Checks

Resolves the transport connection string from the canonical manifest key Router:Messaging:valkey:ConnectionString (compose Router__Messaging__valkey__ConnectionString), parses host:port (and an optional password=), TCP-connects, and performs a real Redis/Valkey handshake: AUTH (only when a password is configured) followed by PING, reading the inline +PONG reply. A transport whose port is open but is half-open or AUTH-rejecting yields fail, not a false pass. The password is never logged or echoed.

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 attempt counts when two or more tenants are present.

This check covers the async messaging backbone — a different integration from:

• check.servicegraph.valkey (the distributed-cache lens of Valkey), and
• the Notify queue-health check (the Notify dependency).

They may resolve the same Valkey today (one backend), but the catalog entries and blast radii differ, so a future split deployment keeps separate signals.

Why It Matters

The Valkey-backed Router transport carries inter-service request/response dispatch. A half-open transport backend stalls cross-service calls platform-wide. A bare TCP connect cannot tell “transport port open” from “transport serving”; the PING handshake can. One docker restart is the documented fix for the metadata-replay flake on this transport.

Common Causes

• The transport Valkey is not running or is half-open / still starting
• Wrong transport host/port or password in Router:Messaging:valkey:ConnectionString
• A non-Redis service is listening on the configured port
• Network/firewall isolation between services and the transport Valkey

How to Fix

Docker Compose

# Restart the transport Valkey to reconnect the backbone (non-destructive: no queue draining).
docker compose -f devops/compose/docker-compose.stella-ops.yml restart valkey
docker compose -f devops/compose/docker-compose.stella-ops.yml ps valkey
redis-cli -h cache.stella-ops.local -p 6379 ping

Bare Metal / systemd

systemctl restart valkey
redis-cli -h <transport-host> -p 6379 ping

Kubernetes / Helm

kubectl rollout restart statefulset/valkey -n stellaops
kubectl get pods -n stellaops -l app=valkey

Verification

stella doctor run --check check.router.messaging.transport

Related Checks

• check.servicegraph.valkey — the Valkey cache (different integration, same possible backend)
• check.servicegraph.gateway-router — the gateway in front of the transport
• check.servicegraph.nats — the alternative NATS transport