Files
boxmaker/docs/plans/M4b/files/runbook-gateway-unreachable.md
T
kyleandClaude Opus 5.5 2d415fc1be Plan M4b: approvals over Mattermost in 15 tasks
Skeletons for new files only; existing files change by exact edits, so no task overwrites an
earlier one's work. Each task's tests were run against a reference built in order from master,
with the gate at each step and mutations checked; each skeleton compiles and fails its tests, and
every todo!() comment was read beside its signature. The reference is kept off this machine.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-24 03:34:21 -07:00

35 lines
1.7 KiB
Markdown

## gateway-unreachable
**What you see.** `brokerd` prints `brokerd: approval <id>: gatewayd is not reachable at <socket>:
<reason>; bxctl can still answer it`, then this entry, once per approval. No approval post
appears in Mattermost. `bxctl approvals` lists the approval as usual.
**Why.** `brokerd.toml` has a `[gateway]` section, so each pending approval is carried to
`gatewayd` to be posted in Mattermost. The courier could not connect to `gateway.sock`, or
`gatewayd` answered that it could not post (Mattermost unreachable). The approval is not lost: it
stays pending, `bxctl` can answer it, and the courier tries again every 5 seconds until it is
posted or answered. When a later try works, `brokerd` prints `brokerd: approval <id> posted in
Mattermost`.
**Confirm.**
```sh
ls -l <socket> # gatewayd creates it at start; [approvals] socket in gatewayd.toml
pgrep -x gatewayd # is it running?
```
and `gatewayd`'s own output: `cannot reach …` there means Mattermost is the problem (see
[mattermost-unreachable](#mattermost-unreachable)).
**Fix.** Start `gatewayd`, or make `[gateway] socket` in `brokerd.toml` and `[approvals] socket`
in `gatewayd.toml` name the same path (both default to `<home>/run/gateway/gateway.sock`). To turn
Mattermost approvals off, remove `[gateway]` from `brokerd.toml` and restart `brokerd`.
**Check.** Trigger an `ask` call: its approval is posted in Mattermost, and `!approve <id>` in
its thread answers it.
Where two Boxmakers share a channel thread, address approval commands to one of them
(`@<bot> !approve <id>`): a bare `!approve <id>` is taken by every Boxmaker with that id pending
in that thread.