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 free

Why 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.

CauseHow to checkFix
Not a published deployThe change is only on a Deploy Preview or a branch deployScheduled functions only run for published deploys. Publish the deploy
No schedule registeredThe Functions page does not show a Scheduled badge on the functionExport config with a schedule property, or add it to netlify.toml, and redeploy
Non-JavaScript functionThe function is not TypeScript or JavaScriptInline schedules only work for TypeScript and JavaScript. Set the cron expression in netlify.toml
Wrong hourThe job runs at an unexpected timeSchedules run in UTC. 0 0 * * * is midnight UTC
Run exceeds the limitThe log ends mid-runThe limit is 30 seconds. Move long work to a background function
Unsupported cron shortcutUsing @reboot or @annuallyNetlify 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:

netlify.tomlTOML
[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

  1. Open the Functions page in the Netlify UI. A scheduled function shows a Scheduled badge and its next run time.
  2. Select the function to see its schedule and logs.
  3. Click Run now to invoke it by hand. This also works on Deploy Previews and branch deploys.
  4. 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.

netlify/functions/daily-sync.mtsTypeScript
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.

ScheduleIntervalGrace period
Every hour1 hour5 minutes
Daily at 02:00 UTC24 hours15 minutes

Set it up in UptimeIO

  1. Create a monitor and choose the Heartbeat type.
  2. Set the interval and grace period from the table above.
  3. Copy the heartbeat URL into the HEARTBEAT_URL environment variable in Netlify, then publish a new deploy.
  4. 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

Start monitoring in a few minutes

Start monitoring free

Free plan · 50 monitors · No credit card required