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

1.7 KiB

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.

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

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.