# Alert when a 2 a.m. job fails

> Researched. Small business · Intermediate · Operations. Updated 2026-11-16.

Canonical page: https://www.aisetupsthatwork.com/setups/get-an-alert-when-a-2-am-job-fails-with-claude-code/

## What it does
Get an email or text when a nightly job fails or never runs, by having Claude Code wrap the script and report to a heartbeat check.

## Who it's for
Owners and one-person IT who run a nightly script on a Mac, Linux machine or server, such as a backup or export, and only learn it failed days later.

## Tools
- A Mac or Linux machine that runs the job from cron, and is on at night
- The command that runs the job, written out in full
- A Healthchecks.io account, or another heartbeat service with the same ping idea
- Claude Code, in the terminal or the desktop app

## Steps
1. Write down the job: the exact command, the time it runs, how long it normally takes and where its output goes now.
2. In Healthchecks.io, create one check for this job. Set the schedule to match cron (a Cron schedule, with the expression from your crontab and your machine's time zone) and set the Grace Time longer than the job normally takes. Copy the check's ping URL.
3. Add at least one notification method, and a second one if the job matters, such as email and a chat or text. Two channels give a second chance if one fails, but neither is a guarantee of delivery.
4. Open Claude Code in a new folder in Manual mode and paste the prompt below with your command. Do not paste the ping URL into the chat or into any file that is shared; the prompt has you put it in an environment variable or a private file.
5. Read what Claude Code wants to do and approve each action. It should write the wrapper and show you the cron line. It should not edit your crontab.
6. Add the cron line yourself with crontab -e. Pick a time outside the hour when the clocks change.
7. Test the failure alert. Run the wrapper by hand with a command that fails, such as false, and wait for the email.
8. Test the missing-run alert. Leave the job off for one scheduled run and confirm the check goes late and alerts after the grace time.
9. Put the check's name, the ping URL location and what to do when it alerts into one note, so whoever gets the alert knows the next step.

## Copy-paste prompt
Adapt bracketed fields to your situation.
```text
I have a nightly job that runs from cron on this machine. Write a small shell script that wraps it and reports to Healthchecks.io.

The job command: /home/shop/bin/export-orders.sh (made-up sample).
Its schedule: 3:30 AM every day (a sample time chosen outside the hour when clocks change; check yours).
It normally takes a few minutes.

The wrapper must:
1. Send a "start" ping, run the job command, and save its output to a log file in a logs folder next to the script.
2. If the job exits with 0, send a success ping. If it exits with any other code, send a failure ping with the exit code, and keep the log.
3. Read the ping URL from an environment variable named HC_PING_URL, or from a private file, never from the script text. Never print the URL.
4. Use curl with a short timeout and a few retries, so a network problem does not hang the job. If the ping fails, write that to the log. Never delete or change the job's own output.
5. Exit with the job's own exit code.

Also:
- Show me the single crontab line to run the wrapper at the same time, loading the ping URL from the private file or environment, never written in the line. Do not edit my crontab yourself.
- Tell me how to test a failure on purpose and how to test a missed run.
- Do not change the job script, do not install anything and do not send anything except the pings. Before you run anything, say what you will do.
```

## Guardrails
- What it touches: Chat input you provide (A Mac or Linux machine that runs the job from cron, and is on at night; The command that runs the job, written out in full).
- Needs your OK: Send, pay, publish, delete, and CRM updates stay with you unless you explicitly opt in.
- Safety level: Drafts for you
- Why a heartbeat instead of email from cron: The Healthchecks.io docs describe heartbeat monitoring as a dead man's switch: the job pings when it finishes, and an alert goes out when the ping does not arrive on time. They say that catches a dead machine, a cron daemon that is not running, a job that exits with an error and a job that runs far too long. They list drawbacks of cron's own MAILTO: the machine needs a configured mail system, you are not told if the machine is off, and a noisy job can bury real errors.
- Time changes and 2 a.m.: The crontab man page says jobs scheduled in the missing hour when clocks change never run, and jobs scheduled in a repeated hour run twice. If the machine is in a place that changes clocks at 2 a.m., pick another time. If pings arrive an hour early or late, the Healthchecks.io docs say to check that the check's time zone matches the machine's.
- What was checked: The Healthchecks.io claims were checked against its docs and the cron points against the crontab man page on Nov 16, 2026. Claude Code claims were checked against the Claude Code docs. Nothing was run end to end.
- Treat the ping URL like a password: Anyone who has the check's ping URL can make the check look healthy. Keep it out of the chat, out of shared repositories and out of the script text. The prompt asks Claude Code to read it from an environment variable or a private file. That is an instruction, not a lock, so look at the script before you run it.
- Claude Code does not watch the job: Claude Code only writes the wrapper. The script and the monitoring service do the watching, after Claude Code is closed. This is separate from the Claude Code scheduled tasks feature, which runs Claude itself on a schedule.
- The cron job has a different PATH or environment from your shell. Use full paths in the wrapper and the cron line.
- The success ping fires even though the job half-failed. The job itself has to exit with a non-zero code when it fails, so test that.
- No alert arrives. Check the notification method on the check, your spam folder and that the check is not Paused.
- The check is always late by an hour. The time zone on the check does not match the machine.
- The machine is off or asleep at night. The check will alert, which is the point. Run the job on a machine that stays on.

## Tips
- Set the grace time longer than the job normally takes, or you get an alert for a slow night.
- Send the alert to two places. The docs recommend more than one channel in case one fails.
- Look at the check page once a week. The service can also send weekly or monthly email reports.

## Estimates (labeled, not measured)
- Time saved: Not stated in sources.
- Money saved: Not stated in sources.
- Tool cost: Claude Code needs a paid Claude plan or a Claude Console account (claude.com/pricing). Healthchecks.io has its own plans and a self-hosted option: see healthchecks.io/pricing. cron is built into macOS and Linux.

## Sources
Summaries use the public sources below, not independent verification.
- Healthchecks.io: https://healthchecks.io/docs/monitoring_cron_jobs/ (How to monitor cron jobs (read Nov 16, 2026): heartbeat or dead man's switch monitoring, the failure modes it catches, grace time, notification redundancy and the drawbacks of MAILTO.)
- Healthchecks.io: https://healthchecks.io/docs/signaling_failures/ (Signaling failures (read Nov 16, 2026): append /fail or a non-zero exit status to the ping URL, and the shell example.)
- Healthchecks.io: https://healthchecks.io/docs/configuring_checks/ (Configuring checks (read Nov 16, 2026): Cron schedules need the cron expression, the server's time zone and a Grace Time; the start signal expects a success within Grace Time.)
- Healthchecks.io: https://healthchecks.io/docs/configuring_notifications/ (Configuring notifications (read Nov 16, 2026): use more than one channel, route by urgency, and the weekly and monthly email reports.)
- Linux man-pages project: https://man7.org/linux/man-pages/man5/crontab.5.html (crontab(5) (read Nov 16, 2026): jobs scheduled in the missing hour at a daylight saving change never run and jobs in a repeated hour run twice; the MAILTO variable; CRON_TZ.)
- Anthropic: https://code.claude.com/docs/en/permission-modes (Claude Code permission modes (read Nov 16, 2026): in Manual mode Claude Code stops and asks before most actions that edit files, run shell commands or reach the network.)

## Get the free starter pack
Five beginner copy-paste AI setups, free by email: https://www.aisetupsthatwork.com/starter-pack/?utm_source=ai-agent&utm_medium=markdown&utm_campaign=setup-get-an-alert-when-a-2-am-job-fails-with-claude-code

Related:
- [Find broken links with Claude Code](https://www.aisetupsthatwork.com/setups/find-broken-links-and-missing-titles-with-claude-code/index.md)
- [Receipts to a sheet with Claude Code](https://www.aisetupsthatwork.com/setups/turn-a-folder-of-receipts-into-a-spreadsheet-with-claude-code/index.md)
- [Stop one job eating your bot usage](https://www.aisetupsthatwork.com/setups/find-which-bot-routine-burns-your-usage/index.md)
