checkId: check.servicegraph.nats plugin: stellaops.doctor.servicegraph severity: warn tags: [servicegraph, nats, messaging, connectivity]
NATS Broker Connectivity
This Doctor check confirms the NATS message broker is reachable and serving when NATS is the configured Router transport, closing a blind spot where NATS-backed inter-service messaging was completely unmonitored.
What It Checks
Resolves the NATS endpoint from the canonical manifest keys Nats:Url / Messaging:Nats:Url (plus the legacy router-transport fallbacks Router:Messaging:nats:Url / Router:Messaging:nats:Host), strips any nats:// scheme, TCP-connects to the endpoint (default port 4222), and reads the NATS INFO protocol line the server sends immediately on connect. The INFO banner proves the listener is a real NATS server, not just an open port. The probe publishes nothing and subscribes to nothing.
This is the Router-transport NATS — distinct from any Notify-queue NATS (a separate catalog entry / check).
| Condition | Result |
|---|---|
| NATS endpoint not configured (NATS is not the transport) | skip |
TCP connects and the server sends an INFO banner | pass |
Port open but no INFO banner (wrong port / half-open) | fail |
| Connection refused / timeout | fail |
Why It Matters
When the Router NATS transport plugin is selected, all inter-service messaging rides NATS. A dead or half-open NATS broker silently breaks async dispatch platform-wide with no Doctor signal. A bare TCP connect cannot distinguish “port open” from “NATS serving”; reading the INFO banner does.
Common Causes
- The NATS server is not running
- A non-NATS service is listening on the configured port (wrong port)
- NATS is half-open / not finished starting
- Firewall blocking the NATS port (4222)
How to Fix
Docker Compose
docker compose -f devops/compose/docker-compose.stella-ops.yml ps nats
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d nats
# Optional monitoring health endpoint (port 8222 when enabled):
curl -fsS http://nats:8222/healthz
Bare Metal / systemd
systemctl restart nats-server
# Confirm the listener answers with an INFO banner:
printf '' | nc -w2 <nats-host> 4222
Kubernetes / Helm
kubectl get pods -n stellaops -l app=nats
kubectl rollout restart statefulset/nats -n stellaops
Verification
stella doctor run --check check.servicegraph.nats
Related Checks
check.servicegraph.mq— RabbitMQ broker connectivity (the other transport option)check.router.messaging.transport— the active Router transport (Valkey backbone)