# 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.