natsClient_JS/docs/8-runbook.md

Runbook: natsClient_JS

Connection Issues

getNats fails to connect

Symptom: connectionStatus lands in error, getNats throws.

Steps:

1. Check the resolved URL precedence: opts.servers → VITE_NATS_URL → config.nats_server_info.url → wss://natsws.yiem.cc (4-specification.md:SP-001).
2. Verify broker reachability: nc -z -w5 <nats-host> <nats-port>.
3. Confirm nats.ws is available (browser/WSS transport, NFR-101).
4. Retry after fixing config; the consumer should call getNats again.

Connection stuck after a disconnect

Symptom: Status stays disconnected and does not return to connected.

Steps:

1. Confirm nc.status() is wired to emit disconnect/reconnect (2-solution_design.md:SD-004).
2. Check nc.closed() for a permanent close (4-specification.md:SP-001).
3. Restart the consuming app to re-establish the shared socket.

References: 4-specification.md:SP-001 (connection), 3-walkthrough.md:#wt-007.

Message Issues

Subscribe receives no messages

Symptom: No onMessage callbacks fire.

Steps:

1. Verify the subject string matches the broker's subject exactly.
2. Confirm the connection reached connected before subscribing.
3. Check the subscription is tracked in the Map (4-specification.md:SP-002).

sendMsghandlerRequest throws

Symptom: throw new Error(data) or No valid response found.

Steps:

1. Confirm the backend returns a jsontable/dictionary payload, not text (4-specification.md:SP-011).
2. Verify msghandlerCSR.smartpack/smartunpack are in use (2-solution_design.md:SD-006).
3. Check the broker envelope format (4-specification.md:SP-010, SP-011).

reply handler produces no response

Symptom: Requests to the subject time out.

Steps:

1. Confirm handler returns a value that gets published on m.subject (4-specification.md:SP-005).
2. Verify the subject is not also consumed by a request on the same endpoint.

Error Code Reference

Error	Symptom	Action	Reference
error status	getNats failed	Fix URL/config, retry	4-specification.md:SP-001
text msghandler payload	sendMsghandlerRequest throws	Confirm backend returns dictionary/jsontable	4-specification.md:SP-011
decode error	subscription message dropped	Handled by per-message guard (NFR-302)	4-specification.md:SP-002

Escalation

• If the shared socket never reconnects (NFR-102), treat the broker as down and page the backend team; the library only reports state via connectionStatus.
• Contact: backend/NATS on-call via the nats_client_reconnect_rate alert.

Post-Incident

• Review logs for root cause ([NATS] ... lines).
• Update this runbook if a new failure mode appears.
• Link findings to 6-validation.md so the case is covered by a test.