Slack Bolt Error Handling: What Users See for Each Failure, Tested
We made Bolt for Python listeners raise, skip ack() and miss an action, then recorded what Bolt logged, what the user saw in Slack and how @app.error changes it. One case is a race: ack() followed at once by an exception still shows the user a failure.
On this page
In Bolt, an exception in a listener goes to the global error handler (@app.error in Python, app.error() in JavaScript). Without one, Bolt logs Failed to run listener function with the traceback, and the user sees a failure only if Slack never got the ack(): a Slackbot notice for a slash command, a warning triangle for a button. We tested 8 failure cases in a Bolt for Python app (slack_bolt 1.30.0, Socket Mode) on 13 November 2026, then added two kinds of error handler.
What each failure looks like
| Listener does | Bolt log (default) | What the user sees |
|---|---|---|
ack() and returns | nothing | nothing |
Slash command raises before ack() | ERROR ... Failed to run listener function (error: boom before ack) + traceback | Slackbot: "/sg1113 failed because the app did not respond. Please try again or contact the app developer." |
Slash command never calls ack() | WARNING ... cmd didn't call ack() and Unhandled request | The same Slackbot notice |
Button: raises before ack() | ERROR ... Failed to run listener function and Unsuccessful Bolt execution result (status: 500, body: ) | Warning triangle next to the button |
Button: never calls ack() | WARNING ... e_noack didn't call ack() and Unhandled request | Warning triangle |
Button: no listener for the action_id | WARNING ... Unhandled request with a suggested @app.action(...) stub | Warning triangle |
Button: ack() then raises at once | ERROR ... Failed to run listener function, then 3 s later WARNING ... e_raise didn't call ack() | Warning triangle |
Button: ack(), 0.2 s of work, then raises | ERROR ... Failed to run listener function | nothing |
The triangle and the Slackbot notice mean the same thing: Slack waited 3 seconds and got no acknowledgement. Neither tells the user what went wrong, and neither is sent to your logs by Slack.
The ack-then-raise race
The surprising row is ack() followed by an exception on the next line. The listener did call ack(), yet the user got a triangle and Bolt logged that ack() was never called. In Bolt for Python's thread runner (slack_bolt/listener/thread_runner.py), when a listener that is not auto-acknowledged raises, the error branch resets ack.response to None if it was already set. The main thread polls for that value every 10 ms, so if the exception comes first, the acknowledgement is erased before it is sent. With 0.2 s of work between ack() and the exception, the acknowledgement had already gone out and the user saw nothing. In real code, put the work that can fail after ack() and catch it there, or use an error handler as below.
Add a global error handler
The first handler logs the error and tells the user through respond():
@app.error
def on_error(error, body, logger, respond):
logger.error("custom handler caught: %r", error)
respond("Something went wrong on our side. The error was logged.")
With it, Bolt no longer printed its own traceback, only our log line. Every failing case got our ephemeral message. For a slash command that raised before ack(), the user got both our message and Slackbot's failure notice, because the command was still never acknowledged:
Never appear "away" on Slack again
Cloud-based. No downloads. Works 24/7 even when your laptop is off.
Return a response from the handler
An error handler can also return a BoltResponse, and Bolt sends it as the acknowledgement:
from slack_bolt import BoltResponse
@app.error
def on_error(error, body, logger):
logger.error("custom handler caught: %r", error)
return BoltResponse(status=200, body="Sorry, that failed. We logged the error.")
With this handler, the slash command that raised before ack() showed only our text as an ephemeral reply, with no Slackbot notice. The button that raised before ack() and the ack-then-raise button showed no triangle.
The body text only shows for slash commands. For buttons the response body is ignored, so send a message with respond() in the same handler if the user should know.
Unhandled requests
A button whose action_id has no listener never reaches the error handler. Bolt answers it with 404 unhandled request and logs a warning with a ready-made stub:
WARNING slack_bolt.App Unhandled request ({'type': 'block_actions', 'block_id': '6b6PX', 'action_id': 'e_unhandled'})
---
[Suggestion] You can handle this type of event with the following listener function:
@app.action("e_unhandled")
def handle_some_action(ack, body, logger):
Bolt for Python has an App(raise_error_for_unhandled_request=True) option that sends these to the error handler instead; we did not run it. If old messages still carry buttons from a removed feature, keep a listener for their action_id that only calls ack().
Notes for Bolt for JavaScript
Bolt JS has the same idea under app.error(async (error) => {...}), and an error thrown before ack() leaves Slack without an acknowledgement in the same way, so the Slackbot notice and the triangle above are Slack's behavior, not Bolt's. We ran only the Python app, so the log lines and the ack race above are Python facts. To tell an error from a missing ack() in your own logs, compare the Failed to run listener function and didn't call ack() lines.
For how say(), respond() and the client differ when you answer the user, see our say vs respond test. If calls fail with invalid_auth or not_authed instead, the token is the problem; the Slack bot token guide shows where each token comes from.
FAQ
Does Slack retry a request that was not acknowledged?
Slash commands and button clicks were delivered once in our Socket Mode tests, with no retry after the 3-second timeout. The Events API is different: it retries events with an x-slack-retry-num header.
Should I call ack() first in every listener?
Yes, unless you need to answer in the acknowledgement itself, such as a modal validation error or a text reply for a slash command. Call ack() first, then do the work, so a slow API call cannot push you past the 3-second limit.
Stop Jiggling Your Mouse.
Join hundreds of remote workers who never worry about their Slack status. Set it up once, stay green forever.
Related Articles
Slack Bolt Middleware: Global and Listener, Tested
Global middleware runs for every request and listener middleware for one listener. We ran both in Bolt for Python and Bolt for JavaScript on 20 November 2026 and logged what Slack did when next() was skipped: Python answered 404 and Slack sent the event again.
Testing a Slack Bolt App with pytest: What Worked, What Did Not
Three layers that tested a Bolt for Python app on 17 November 2026: pure functions, listeners called with fakes, and signed requests through app.dispatch against a local mock Web API, plus one live check. A subclassed WebClient and the default threading both made tests fail; here is why.
Slack Bolt with Express: ExpressReceiver and customRoutes, Tested
Two ways to serve your own HTTP routes next to a Bolt JS app: ExpressReceiver with receiver.router, or customRoutes on the built-in receiver. We ran both with Bolt 5.1.0 and Express 5.3.0 on 17 November 2026, plus the body-parser mistake that makes every slash command fail.