Skip to content
Delay Docs

Debug a failed run

When a cron or job fails, its run record shows what Delay sent, what came back and why it counted as a failure. Start from the failure, read the run, reproduce the request, then run it again.

Find the failure

Start wherever the failure showed up:

  • Dashboard: a red banner reads “N cron jobs are failing” with a view affected jobs link. The 7-day success card and the Activity chart show whether failures are new or ongoing.
  • Alerts: if alerting is on, the Alerts tab lists each failure with its source. Cron alerts also carry the failure reason; use the reason filter (All reasons) to group them.
  • Cron jobs: failing crons show Failed in the Status column, and Last run shows the status code or the reason, such as “Assertion failed”.
  • Jobs: the Failed tab lists failed attempts. Retrying lists jobs that are waiting for a retry. Narrow down with All queues and Search URL.
  • Dead letters: jobs that used up all their retries. Choose View details in a row’s menu to open the job.

Read the run

  1. Open the run. For a cron, open it from Cron jobs. Recent executions shows the last 10 runs. Click View all for the Execution history, then click a row to expand it. For a job, click it in the Jobs list.

  2. Check the status and the error message. The status code tells you what your endpoint answered. The error message tells you why Delay counted it as a failure, for example HTTP 503 error, Assertion failed: Response body does not contain "ok", or a connection or timeout error from the HTTP client. In the Jobs list, the Status column also shows the failure reason label and the attempt number.

  3. Look up the reason. Each reason has a cause and a fix in the failure reasons table. The cron execution history doesn’t show the reason label, but the status code or error message tells you which row applies.

  4. Read the response. Open Response Body and Response Headers (crons) or the Response section (jobs). Error pages, validation messages and auth failures usually explain themselves there.

  5. Check what was sent. Open Request Headers and Request Body (crons) or the Request section (jobs). Only the headers you configured are listed; Delay’s own headers are sent but not shown. A cron’s plain-text payload is listed as you wrote it, but it is sent wrapped as {"body": "..."}.

  6. Compare the duration with the timeout. A duration close to the request timeout points to a slow endpoint. Duration is shown in the cron’s history and in the Jobs list.

Reproduce the request

Send the same request yourself to see what your endpoint does with it. Use the URL, method, headers and body from the run, plus the headers Delay always adds:

Terminal window
curl -i -X POST https://api.yourapp.com/backup \
  -H "Content-Type: application/json" \
  -H "User-Agent: GuzzleHttp/7" \
  -H "X-Api-Key: your-endpoint-key" \
  --max-time 30 \
  -d '{"type":"full"}'

-i prints the status line and headers. Don’t add -L: Delay doesn’t follow redirects, so if you see a 3xx here, that’s the failure. Set --max-time to the run’s request timeout. If you sign requests, your endpoint may also require X-Delay-Signature and X-Delay-Timestamp; see Verify requests from Delay.

If the request works from your machine but fails from Delay, the cause is usually reachability: a firewall or allowlist blocking outside traffic, a private IP address, or a hostname that only resolves inside your network. See Write endpoints Delay can call.

Run it again

After you’ve fixed the cause:

  • Cron: click Run now on the cron’s page. Otherwise the next scheduled run picks up the fix, since crons don’t retry.
  • Job still retrying: nothing to do. The next retry uses the same request.
  • Dead-lettered job: on Dead letters, choose Replay in the row’s menu. Delay creates a new job with the same request. See Replay failed jobs.
  • Other failed jobs: on the Jobs list, select them and click Retry (N) in the bar at the bottom. Each becomes a new job.

Spot patterns

Single failures are easy. These views help with the ones that keep coming back:

You want to knowWhere to look
Is this cron getting worse?Success rate on the cron’s page (its last 10 runs)
Is the endpoint slowing down?The response time chart on a cron or queue page: average, p95, min and max over 30 days
Is a queue failing more this week?The Activity column on Queues (7 days)
Are failures piling up?The count on Dead letters
What’s failing right now?Unread alerts on Alerts, and the bell in the header
Will we hit the monthly limit?The Usage tab: requests used, remaining and projected

If failures cluster at the same time of day, look at what else runs then: backups, deploys, traffic peaks, or several of your crons starting in the same minute (see Spread out your schedules).

To feed results into your own monitoring, set a callback URL: Delay POSTs a short summary after each cron run and when a job finishes. See Callbacks.

Next steps