Workly

Debugging

You should never have to wonder what your queue is doing.

Every attempt is kept with its status code, error, response body and timing. Failures are grouped by error, alert you by email or Slack, and can be replayed on your laptop and retried in one go once the fix is in. The dashboard comes with the server, so there's nothing to bolt on.

Workly keeps every attempt and its response.

A task keeps the request Workly sent and every response it got, so a failed task shows why it failed.

A failed task in the Workly dashboard, explaining why it failed, with every attempt's response.

Every attempt

Status code, error, response headers, the first 4 KB of the body, and timing, for every delivery, not just the last one.

How it ended

Success, an HTTP error, a timeout, a network error, or lost when Workly stopped mid-delivery, so you know whether the endpoint got the request.

Why Workly gave up

A failed task says whether it ran out of attempts or got a 4xx that isn't retried, and which setting to change if that was wrong.

Queue health

Each queue's backlog, what's running, how far behind it is, and its last 24 hours: succeeded, failed, and p50 and p95 duration.

What to do when tasks fail.

  1. 01

    Get an alert

    Within about a minute of a failure, an alert by email or Slack names the queue or schedule, how many failed and the most common errors, with links.

  2. 02

    Find the cause

    Failed tasks are grouped by error. One look tells a bad deploy (one error, hundreds of tasks) from a bad record (one task).

  3. 03

    Replay it locally

    Get the exact signed request a task sends, as a curl command, and replay it against the handler on your laptop.

  4. 04

    Retry the failures

    Once the fix is out, retry one task, one group of failures or the whole queue. Each gets a fresh set of attempts.

Terminal
$ workly queues failures invoices
TASKS  ERROR                              LAST FAILED  LATEST TASK
  212  HTTP 503 Service Unavailable       2m ago       task_01J9ZK3M5Q…
    3  HTTP 422 Unprocessable Entity      40m ago      task_01J9ZH8T2R…
    1  no response within 30s             1h ago       task_01J9ZD4W7N…

Retry one group: workly queues retry-failed invoices --error '<ERROR>'

$ workly queues retry-failed invoices --error 'HTTP 503 Service Unavailable'
Retrying 212 failed tasks.

Alerts by email and Slack.

Workly alerts you when a task or schedule run fails for good, so you don't have to watch the dashboard.

Email and Slack

Add channels in the dashboard or the API, and send a test alert to check one works. On workly.run, email alerts go to the workspace's members.

At most one every 30 minutes

After the first alert, a queue or schedule alerts at most every 30 minutes, covering everything since. Failures in several queues at once arrive as one alert.

Only failures that are final

A task alerts once it has used up its attempts or got a response that isn't retried. Retries that later succeed, and cancelled tasks, never do.

Debug from your coding agent over MCP.

Every Workly server speaks MCP. Point Claude Code, Cursor or Codex at it and your agent can read failures, get the exact request a task sends, replay it against your local handler, and retry once the fix is in. A self-hosted server offers agents read-only tools unless you turn on the rest; on workly.run you choose read-only or read and write when you connect.

>Why are tasks in the invoices queue failing in prod?
>Enqueue a test task to my local /tasks/send-email handler and tell me how it answered.
>Why hasn't last night's daily-refresh workflow finished?
>I fixed the handler. Retry the failed tasks and check the first one succeeds.

Questions

How do I find out why a background job failed?
Open the task in the dashboard. It has every attempt with its status code, error, response headers and the start of the response body, and says why Workly stopped retrying. The queue's page groups all its failed tasks by error, so you see whether it's one bad record or every task since a deploy.
Can I retry failed jobs after fixing the bug?
Yes. Retry one task, every task that failed with one error, or every failed task in a queue, from the dashboard, the CLI, the API or your coding agent. Each retried task gets a fresh set of attempts, and its callback, if it has one, fires again with the new outcome.
How do I get alerted when jobs fail?
Add an email address or a Slack incoming webhook as an alert channel. Workly alerts within about a minute of a task or schedule run failing for good, then at most every 30 minutes per queue or schedule while failures continue.
Can my coding agent debug the queue?
Yes. Every Workly server has an MCP endpoint, so Claude Code, Cursor, Codex and other agents can list failures, read attempts, replay a delivery against your local handler and, if you allow it, retry tasks once the fix is in. On workly.run, agents sign in and you choose read-only or read and write.
Does Workly export metrics?
A self-hosted server serves Prometheus metrics: attempts by outcome, queue depth, dispatch lag, the age of the oldest due task and when each schedule last succeeded. On workly.run, the dashboard shows each queue's health and the last 24 hours.

Try it in five minutes.

workly dev gives you a server and dashboard on your laptop with nothing else to start, and the Python and TypeScript SDKs let your app enqueue to it. Or sign in to hosted Workly and get a workspace and an API key in a minute, free on the Hobby plan.