Vercel cron job not running? Find the cause and get alerted

A Vercel cron job that does not fire leaves an empty log, not an error. 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

Cron jobs only run on production deployments, use UTC, and do not follow redirects, and Hobby runs can land anywhere in the scheduled hour. Vercel does not retry a failed run, so add a heartbeat request at the end of the cron route and alert when it stops arriving.

Monitor your Vercel cron jobs free

Why Vercel cron jobs stop running

Vercel triggers a cron job by sending an HTTP GET request to the path in vercel.json on your production deployment. The request has the user agent vercel-cron/1.0. If that request never arrives, or your route fails, Vercel does not tell you.

CauseHow to checkFix
Not a production deploymentThe project only has a Preview deployment, or the change is not promotedCron jobs only run on Production. Deploy to production
Cron not registeredRun vercel build --prod and look for crons in .vercel/output/config.jsonFix vercel.json so the build registers it
Path redirectsThe route returns a 3xx, for example because trailingSlash is enabledCron does not follow redirects. Use the final path, with the trailing slash if needed
Wrong path or routeThe path in vercel.json differs from the route in the Deployment SummaryUpdate the cron path. A missing route still runs and returns 404
Bad CRON_SECRETThe variable has a newline or special charactersRemove characters that cannot go in an authorization header
Firewall ruleCustom WAF rules are blocking the requestReview your Vercel WAF rules
Wrong scheduleThe job runs at an unexpected hourSchedules are in UTC. Check the expression in a cron generator
Hobby timingThe job runs at an unexpected minute, or not every hourHobby allows one run per day, at any point in the scheduled hour

There is also a cause you cannot fix. Vercel describes cron delivery as best effort: a transient network error can stop a request reaching your function, and then no runtime log is created for that run. The same scheduled run can also occasionally be delivered twice.

Check the basics

  1. Open the project in the Vercel dashboard, go to Settings, then Cron Jobs. Confirm the job is listed and not disabled.
  2. Select View Logs. This opens runtime logs filtered by requestPath, for example requestPath:/api/cron.
  3. If the logs stay empty, add export const dynamic = 'force-dynamic' to the route handler so it runs on every invocation.
  4. Request the route yourself with curl. Cron jobs are normal API routes, so a 401, 404 or 3xx shows up immediately.

Local dev servers such as next dev do not run cron schedules, so a job that works on localhost proves nothing about the schedule. Responses that are redirects also do not appear in the logs.

Add a heartbeat to the cron route

Logs only help if the function ran. With a heartbeat, the route 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, rejected or crashed.

app/api/cron/route.tsTypeScript
import type { NextRequest } from 'next/server';

export const dynamic = 'force-dynamic';

const HEARTBEAT_URL = process.env.HEARTBEAT_URL;

async function doWork(): Promise<void> {
  // Your job: sync data, send emails, clean up rows.
}

export async function GET(request: NextRequest) {
  const cronSecret = process.env.CRON_SECRET;
  if (!cronSecret || request.headers.get('authorization') !== `Bearer ${cronSecret}`) {
    return new Response('Unauthorized', { status: 401 });
  }

  try {
    await doWork();

    // Only reached when doWork() did not throw.
    if (HEARTBEAT_URL) {
      await fetch(HEARTBEAT_URL, { signal: AbortSignal.timeout(10_000) });
    }
    return Response.json({ success: true });
  } catch (error) {
    console.error('cron failed', error);
    return Response.json({ success: false }, { status: 500 });
  }
}
vercel.jsonJSON
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    { "path": "/api/cron", "schedule": "0 2 * * *" }
  ]
}

Set HEARTBEAT_URL in the project'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 sits after doWork() inside the try, so a thrown error skips it. The timeout keeps a slow network from using up the function duration, which is the same limit as other Vercel Functions. If the ping itself fails, the route returns 500 and the error shows up in the Vercel logs.

Pick an interval and grace period

The interval is how often the job should run. The grace period is how late a ping can be before you are alerted. Vercel's timing precision depends on your plan, so the grace period does too.

Vercel planTimingSuggested monitor settings
HobbyOnce per day, at any point in the scheduled hour. 0 1 * * * can run between 1:00 and 1:59Interval 24 hours, grace period 1 hour (the maximum). Keep the job short, since its run time adds to the delay
Pro / EnterpriseWithin the minute you specify, at most once per minuteInterval equal to the schedule, grace period longer than your slowest run

For a job that runs every 15 minutes and takes up to a minute, an interval of 15 minutes with a 5-minute grace period is a sensible start. Tighten it once you have seen a few weeks of real run times.

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 Vercel, then redeploy to production.
  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 Vercel cron job not running?
Common causes are a non-production deployment, a path that redirects, a cron entry not registered at build time, a bad CRON_SECRET, or a WAF rule blocking the request. Cron jobs only run on production deployments and do not follow redirects.
Where are Vercel cron logs?
In the project dashboard under Settings, Cron Jobs, select View Logs. It opens runtime logs filtered to the route. If a request never reached your function, there is no log for that run.
Does Vercel retry a failed cron job?
No. Vercel does not retry an invocation when a cron job fails, so a failed run stays failed until the next scheduled time.
Why does my Hobby cron job run at a different time?
Hobby cron jobs run once per day and can be invoked at any point in the specified hour. An expression like 0 1 * * * can run between 1:00 and 1:59 UTC.
How do I get an alert when a Vercel cron job fails?
Send a request to a heartbeat URL at the end of the cron route, 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