Slack Bolt 3-Second Ack Timeout Discipline Prompt
Audit and redesign Bolt listeners so every interaction acks within 3 seconds and slow work moves off the request path, eliminating dispatch_failed and operation_timeout errors.
- Target user
- Engineers debugging Bolt timeout and dispatch_failed errors
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior platform engineer who has chased down every flavor of Slack's 3-second timeout: `dispatch_failed`, `operation_timeout`, and the dreaded "this app responded with an error." I will provide: - My Bolt runtime ([Bolt JS / Bolt Python]) - The listener types I use (commands, actions, view submissions, events) - Symptoms ([intermittent dispatch_failed / users see a timeout warning / double-fires]) - What my handlers actually do (DB calls, HTTP to slow backends, LLM calls) Your job: 1. **The 3-second rule** — explain precisely what must happen in 3 seconds for each interaction type: commands/actions need `ack()`; view submissions need `ack()` (optionally with `response_action`); events on Socket Mode need their envelope acked. Slow work must NOT happen before the ack. 2. **Ack-first refactor** — for each listener, show the ack-first pattern: call `ack()` immediately, then do slow work and respond out-of-band via `respond()`, `client.chat.postMessage`, or `views.update`. 3. **Modal-specific nuance** — for view submissions, you only get one `ack()` and it carries `response_action`; you cannot ack twice to both validate and show a loading state. Show the correct loading-modal-then-update pattern. 4. **Background execution** — where the slow work should run (in-process queue, external worker, `setImmediate`/task) and why a fire-and-forget after ack still needs error handling and observability. 5. **Diagnosing double-fires** — when a missed ack causes Slack to retry, you get duplicate handler invocations; tie this back to idempotency. 6. **Instrumentation** — log ack latency per listener so you catch creeping slowness before it crosses 3 seconds. Output as: (a) per-interaction ack requirements table, (b) before/after refactor for one slow listener, (c) modal loading-state pattern, (d) background-work design, (e) double-fire/idempotency notes, (f) ack-latency instrumentation snippet. Safety: never call ack() after slow work; error-handle the post-ack background path so failures are visible, not swallowed.
Why this prompt works
Slack’s 3-second response window is the single most common thing Bolt developers get wrong, and the failure is insidious because it only shows up under load or when a backend is slow. A handler that calls the database and then acks works perfectly in dev and fails intermittently in production, and the resulting dispatch_failed errors are maddening to correlate. This prompt makes the ack-first ordering the explicit subject, forcing the model to show that ack() must precede all I/O — the one rule that fixes the majority of these incidents.
The modal nuance is where this prompt earns its place alongside generic “respond fast” advice. View submissions give you exactly one ack, and that ack carries response_action, so you cannot use a second ack to show a loading state. Engineers routinely try and get confused when it doesn’t work. By calling out the loading-modal-then-views.update pattern specifically, the prompt produces output that handles the genuinely tricky case rather than the easy one.
Tying missed acks back to double-fires and idempotency closes the loop. A blown ack deadline doesn’t just show a warning to the user — it makes Slack retry, which re-invokes your handler, which can run the side effect twice. Demanding ack-latency instrumentation means the human reviewer gets the telemetry to catch creeping slowness before it crosses the threshold, turning a recurring mystery into a monitored metric.