Improve error message when failing to send task to worker

[juliusgeo]

Description

Improves the error message surrounding tasks failing to be dispatched to the worker with helpful advice for the user. This goes along with the recent change from using a fixed backlog of tasks being dispatched, to failing when a task times out attempting to acquire the sender lock #3290.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Documentation change (pure documentation change)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (non-breaking changes to code which doesn't change any behaviour)
• CI (any automation pipeline changes)
• Chore (changes which are not directly related to any business logic)
• Test changes (add, refactor, improve or change a test)
• This change requires a documentation update

What's Changed

• Add a list of tasks or features here...

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hatchet-docs	Ready	Preview, Comment	Mar 22, 2026 4:17pm

[github-actions]

Benchmark results

goos: linux
goarch: amd64
pkg: github.com/hatchet-dev/hatchet/internal/services/dispatcher
cpu: AMD Ryzen 9 7950X3D 16-Core Processor          
                  │ /tmp/old.txt  │          /tmp/new.txt          │
                  │    sec/op     │    sec/op      vs base         │
LockAcquisition-8   637.8n ± 110%   684.5n ± 103%  ~ (p=0.240 n=6)

                  │ /tmp/old.txt │         /tmp/new.txt          │
                  │     B/op     │     B/op      vs base         │
LockAcquisition-8   332.5 ± 150%   334.5 ± 137%  ~ (p=1.000 n=6)

                  │ /tmp/old.txt │         /tmp/new.txt         │
                  │  allocs/op   │  allocs/op   vs base         │
LockAcquisition-8    4.000 ± 50%   4.000 ± 25%  ~ (p=1.000 n=6)

_{Compared against main (db140b7)}

[promptless-for-oss]

📝 Documentation updates detected!

Updated existing suggestion: Update flow control env var from backlog size to lock acquisition timeout

---

Tip: Filter the Dashboard by labels or assignees to focus on what matters to you 🔎

[mrkaye97]

how does this look when it renders on the FE when it happens?

[juliusgeo]

@mrkaye97 Looks like this!

[mrkaye97]

@mrkaye97 Looks like this!

Thanks! Does it also show up in the activity tab inline with the failure event? if not (or if it does but looks fine), then this is great 👍

[juliusgeo]

@mrkaye97 It does show up inline (kinda), but you have to click on view error first