Netlify scheduled function not running? Find the cause and get alerted
A Netlify scheduled function that does not fire gives you no error, only a function that never executes. Here is how to find the cause, and how to get an alert the next time a run is missed or fails.
Updated
Short answer
Scheduled functions only run on published deploys, in UTC, and stop at 30 seconds. Deploy Previews and branch deploys never trigger them. Add a heartbeat request at the end of the function, sent only after the work succeeds, and alert when it stops arriving.
Monitor your Netlify functions freeWhy a scheduled function does not run
Netlify runs the function on its cron expression and nobody is watching the result. If the schedule is not registered, or the run fails, you see nothing unless you open the function logs.
| Cause | How to check | Fix |
|---|---|---|
| Not a published deploy | The change is only on a Deploy Preview or a branch deploy | Scheduled functions only run for published deploys. Publish the deploy |
| No schedule registered | The Functions page does not show a Scheduled badge on the function | Export config with a schedule property, or add it to netlify.toml, and redeploy |
| Non-JavaScript function | The function is not TypeScript or JavaScript | Inline schedules only work for TypeScript and JavaScript. Set the cron expression in netlify.toml |
| Wrong hour | The job runs at an unexpected time | Schedules run in UTC. 0 0 * * * is midnight UTC |
| Run exceeds the limit | The log ends mid-run | The limit is 30 seconds. Move long work to a background function |
| Unsupported cron shortcut | Using @reboot or @annually | Netlify does not support those two. Use @yearly or a full expression |
Define the schedule
For TypeScript and JavaScript, export a config object with a schedule property from the function file. This needs the @netlify/functions package installed.
Or set the schedule in netlify.toml at the root of the repository:
[functions."daily-sync"]
schedule = "0 2 * * *"Netlify also accepts @hourly, @daily, @weekly and @monthly. Scheduled functions do not accept payloads or POST data, and you cannot invoke one with a URL.
Check the basics
- Open the Functions page in the Netlify UI. A scheduled function shows a
Scheduledbadge and its next run time. - Select the function to see its schedule and logs.
- Click Run now to invoke it by hand. This also works on Deploy Previews and branch deploys.
- Locally,
netlify functions:invoke <function-name>calls the handler once. Netlify Dev never runs it on a schedule.
A function that works with Run now or on your machine proves the code, not the schedule. Check the badge and the next run time to confirm the schedule is live.
Add a heartbeat to the function
Logs only help if the function ran. With a heartbeat, the function sends a request to a unique URL when it finishes, and you get an alert when that request does not arrive. You do not need to know whether the run was skipped, timed out or threw.
import type { Config } from '@netlify/functions';
async function doWork(): Promise<void> {
// Your job: sync data, send emails, clean up rows.
}
export default async (): Promise<void> => {
await doWork();
// Only reached when doWork() did not throw.
const url = process.env.HEARTBEAT_URL;
if (url) {
await fetch(url, { signal: AbortSignal.timeout(5_000) });
}
};
export const config: Config = {
schedule: '0 2 * * *',
};Set HEARTBEAT_URL in the site's environment variables to your heartbeat URL, which looks like https://heartbeat.uptimeio.com/heartbeat/YOUR_HEARTBEAT_TOKEN. Treat it like a password.
The ping comes after doWork() with no catch, so a thrown error skips it. The 30-second limit covers the whole run, ping included, so keep the timeout short. If the ping itself fails, the error shows up in the function log.
Pick an interval and grace period
Set the interval to match the schedule. The grace period is how late a ping can be before you are alerted. Because a scheduled function stops at 30 seconds, a small grace period works.
| Schedule | Interval | Grace period |
|---|---|---|
| Every hour | 1 hour | 5 minutes |
| Daily at 02:00 UTC | 24 hours | 15 minutes |
Set it up in UptimeIO
- Create a monitor and choose the Heartbeat type.
- Set the interval and grace period from the table above.
- Copy the heartbeat URL into the
HEARTBEAT_URLenvironment variable in Netlify, then publish a new deploy. - Choose where alerts go: email, Slack, Telegram, Pushover or a webhook.
Heartbeat monitors are on every plan, including Free. A few details worth knowing:
- Intervals: 1 minute to 24 hours, with a grace period of 1 second to 24 hours. The shortest interval is 5 minutes on Free and 1 minute on Pro and Scale.
- Requests: GET or POST, no authentication.
- Incidents: an incident opens when a ping is late, and resolves after 3 on-time pings in a row.
Questions
- Why is my Netlify scheduled function not running?
- Scheduled functions only run for published deploys, so Deploy Previews and branch deploys never trigger them. Also check that the Functions page shows a Scheduled badge, and that the cron expression is in UTC.
- Where are Netlify scheduled function logs?
- On the Functions page in the Netlify UI. Select the scheduled function to see its schedule and logs.
- How long can a Netlify scheduled function run?
- Up to 30 seconds. For longer tasks, Netlify recommends background functions.
- What time zone do Netlify scheduled functions use?
- UTC. The expression 0 0 * * * runs every day at midnight UTC.
- How do I get an alert when a Netlify scheduled function fails?
- Send a request to a heartbeat URL at the end of the function, only after the work succeeds. The heartbeat monitor alerts you when the request does not arrive, which also covers runs that never started.
Related
- Cron job monitoring - How UptimeIO heartbeat monitoring works and which plans include it.
- Vercel cron job not running - The same problem for Vercel cron routes.
- Cron expression generator - Build a schedule and preview its next run times.
- Heartbeat monitoring docs - Settings, ping examples, metadata, and rate limits.