Nov 18, 20269 min read

Vercel Cron Jobs: How They Work, Their Limits, and Making Them Reliable

What Vercel does when a cron job fires, the plan limits and delivery guarantees that catch teams out, the code patterns that make scheduled work safe, and when to move it to a backend with queues.

Illustration for Vercel Cron Jobs: How They Work, Their Limits, and Making Them Reliable

Vercel Cron Jobs are the shortest path from "this should run every night" to something running every night: one entry in vercel.json, one route handler, and a deploy. That simplicity hides a few delivery properties that matter once the job charges cards, sends emails or syncs data with another system.

This guide covers what Vercel does when a cron job fires, the limits by plan, the failure modes that come from the delivery model, the code patterns that make scheduled work safe on Vercel, and the point where scheduled work belongs in a backend with a queue.

How Vercel Cron Jobs Work

A cron job is a path and a schedule in vercel.json:

{ "$schema": "https://openapi.vercel.sh/vercel.json", "crons": [ { "path": "/api/cron/invoice-reminders", "schedule": "0 7 * * *" } ] }

At each scheduled time Vercel sends an HTTP GET to that path on the production deployment, which runs the function behind it. A few details from the docs shape everything else:

  • UTC only. The schedule is always interpreted in UTC. 0 7 * * * is 07:00 UTC, which moves relative to local time when daylight saving changes.
  • Production only. Preview deployments do not run cron jobs.
  • No named days or months. Expressions such as MON or JAN are not supported, and day-of-month and day-of-week cannot both be set.
  • No redirects. A 3xx response ends the invocation. A Next.js app with trailingSlash enabled redirects /api/cron to /api/cron/, so the function never runs unless the path in vercel.json already has the slash.
  • Legacy status. Vercel now describes Cron Jobs as a legacy feature that will be migrated to Schedules, which add timezones, private targets and runtime-created schedules. Schedules are in beta.

Limits by Plan

HobbyProEnterprise
Cron jobs per project100100100
Minimum intervalOnce per dayOnce per minuteOnce per minute
PrecisionAnywhere within the hourPer minutePer minute
Max duration (fluid compute)300s800s (1800s in beta)800s (1800s in beta)

On Hobby, an expression that runs more than once a day fails the deployment, and 0 1 * * * can fire at any time between 01:00 and 01:59. Duration limits are the function limits from the Vercel Functions limits page, since every cron run is a function invocation. A run that exceeds the limit ends with a 504 FUNCTION_INVOCATION_TIMEOUT.

What Catches Teams Out

The Managing Cron Jobs page is direct about the delivery model, and each point has a practical consequence.

No retries. If the function throws or times out, Vercel does not invoke it again. A nightly billing run that fails at 02:00 stays failed until someone notices.

Best-effort delivery. Occasionally a transient network error keeps the request from reaching the function at all. In that case there is no runtime log for the run, so a missing run does not show up as an error anywhere.

Duplicate runs. The same scheduled run can occasionally be invoked more than once. A job that does "add 10 credits to every active user" can do it twice.

Overlapping runs. If a run takes longer than the interval, Vercel can start the next one while the first is still going. A five-minute job scheduled every minute ends up with several copies working on the same rows.

No local trigger. Cron jobs are not triggered by vercel dev or next dev. You test by calling the route yourself, which does not exercise the schedule, the CRON_SECRET header or the redirect behavior.

Secrets are per deployment. A deployment captures CRON_SECRET when it builds. Changing the variable in project settings does nothing until the next deploy, and promoting or rolling back changes which copy Vercel sends.

Most HTTP-triggered schedulers behave this way, and on all of them the guarantees have to come from your code.

Making Scheduled Work Safe on Vercel

Three patterns cover most of it: check the secret, take a lock, and make the work a reconciliation rather than a one-shot action.

Check the Secret

Vercel sends Authorization: Bearer <CRON_SECRET>. Reject anything else, including the case where the variable is missing.

Take a Lock

A Postgres advisory lock is enough to stop overlapping runs if the job already uses Postgres. pg_try_advisory_lock returns false immediately when another session holds the lock, so a second copy exits instead of waiting.

Reconcile Instead of Act

Rather than "send reminders for invoices due today", query "invoices due, unpaid, and not yet reminded", and mark each one as reminded as the job claims it. A duplicate run finds nothing left to do, and a missed run is caught up by the next one, since yesterday's unreminded invoices still match.

// app/api/cron/invoice-reminders/route.ts import { Pool } from "pg"; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const LOCK_ID = 727001; // any constant unique to this job export async function GET(request: Request): Promise<Response> { const secret = process.env.CRON_SECRET; if (!secret || request.headers.get("authorization") !== `Bearer ${secret}`) { return new Response("Unauthorized", { status: 401 }); } const client = await pool.connect(); try { const lock = await client.query<{ ok: boolean }>( "SELECT pg_try_advisory_lock($1) AS ok", [LOCK_ID]); if (!lock.rows[0].ok) { return Response.json({ skipped: "another run is in progress" }); } // Reconcile: everything due and not yet reminded, including missed days. const due = await client.query<{ id: string; email: string }>( `SELECT id, email FROM invoices WHERE due_date <= current_date AND paid_at IS NULL AND reminded_at IS NULL ORDER BY due_date LIMIT 500`); let sent = 0; for (const inv of due.rows) { // Claim the row first so a duplicate run cannot send the same reminder. const claimed = await client.query( "UPDATE invoices SET reminded_at = now() WHERE id = $1 AND reminded_at IS NULL", [inv.id]); if (claimed.rowCount === 1) { await sendReminder(inv.email, inv.id); sent++; } } return Response.json({ sent, remaining: due.rows.length === 500 }); } finally { await client.query("SELECT pg_advisory_unlock($1)", [LOCK_ID]); client.release(); } } async function sendReminder(email: string, invoiceId: string): Promise<void> { // Call your email provider here, passing invoiceId as its idempotency key. }

The LIMIT 500 keeps one run inside the duration limit. The next run continues where this one stopped. If an email call fails after the row is claimed, that reminder is lost for this cycle, which is the trade-off of claiming first. Claiming after the send risks a duplicate email instead. Pick the failure you can live with, or use an outbox table that a separate run retries.

Add an alert for silence, too. A dead man's switch style check, where the job pings a monitor on success and the monitor alerts when a ping does not arrive, is the only way to notice a run that Vercel never delivered.

What Schedules Change

Vercel Schedules (beta) address several of these points. They support any IANA timezone, can target a private function or a Vercel Queue topic instead of a public path, run on preview branches as well as production, keep execution history per schedule, and can be paused or run on demand without a redeploy. A schedule that publishes to a queue gets the queue's retries for the processing step. On Hobby, Schedules can run every 15 minutes rather than once a day.

They are still in beta, with behavior, APIs and limits subject to change before general availability, and the duration limit for the function doing the work is unchanged. For new projects that will stay on Vercel, Schedules are the better starting point than Cron Jobs.

When Scheduled Work Belongs in a Backend

Cron on Vercel works well for light, frontend-adjacent tasks: revalidating a cache, rebuilding a sitemap, pruning old sessions. It gets uncomfortable when the scheduled job is a batch of business operations, such as billing every account, syncing every tenant with a CRM or generating every monthly statement. Those want a scheduler that hands work to a queue, per-item retries with backoff, a dead-letter queue for items that keep failing, and no duration ceiling on the batch as a whole.

How Encore Handles Scheduled Work

Encore is a backend framework for TypeScript and Go with built-in infrastructure, so a cron job, a queue and a database are declared in code. A CronJob calls an API endpoint on a schedule. Scheduling is managed by the Encore platform and needs no extra cloud resources, though cron jobs do not run locally or in preview environments, so you call the endpoint directly to test it. The pattern below fans the batch out to Pub/Sub, so each invoice is retried on its own.

// billing/reminders.ts import { api } from "encore.dev/api"; import { CronJob } from "encore.dev/cron"; import { Topic, Subscription } from "encore.dev/pubsub"; import { SQLDatabase } from "encore.dev/storage/sqldb"; const db = new SQLDatabase("billing", { migrations: "./migrations" }); interface ReminderDue { invoiceId: string; } export const remindersDue = new Topic<ReminderDue>("reminders-due", { deliveryGuarantee: "at-least-once", }); // Called by the cron job: publish one message per invoice that needs a reminder. export const enqueueReminders = api({}, async (): Promise<void> => { const rows = db.query<{ id: string }>` SELECT id FROM invoices WHERE due_date <= current_date AND paid_at IS NULL AND reminded_at IS NULL`; for await (const row of rows) { await remindersDue.publish({ invoiceId: row.id }); } }); const _ = new CronJob("invoice-reminders", { title: "Queue invoice reminders", schedule: "0 7 * * *", endpoint: enqueueReminders, }); // Each message is processed and retried on its own. const __ = new Subscription(remindersDue, "send-reminder", { handler: async ({ invoiceId }) => { await db.exec` UPDATE invoices SET reminded_at = now() WHERE id = ${invoiceId} AND reminded_at IS NULL`; // sendReminder(invoiceId) goes here; throw to have the message retried. }, retryPolicy: { minBackoff: "10s", maxBackoff: "10m", maxRetries: 8 }, });

A failing invoice is retried with backoff and, after the last attempt, moved to a dead-letter queue, while the other invoices go through. encore run starts the database and an in-memory Pub/Sub locally. On deploy to your own account, the topic becomes SNS with SQS and a dead-letter queue on AWS, or Pub/Sub with a dead-letter topic on GCP, next to an RDS or Cloud SQL database. The handler is still at-least-once, so the reminded_at check in the update stays. The database docs cover the migrations behind the invoices table.

Choosing

JobGood fit
Revalidate pages, rebuild a sitemap, prune sessionsVercel Cron Jobs or Schedules
Daily digest at 09:00 in each user's timezoneVercel Schedules (beta) or a backend scheduler
Batch of payments, emails or syncs that each need retriesCron plus a queue in a backend
Job that runs longer than 800 secondsA backend worker, not a function

Frequently asked questions

How do Vercel Cron Jobs work?

You add a crons array to vercel.json with a path and a cron expression. At each scheduled time Vercel sends an HTTP GET request to that path on your production deployment, which runs the matching function. Schedules are always in UTC, and cron jobs only run for the production deployment.

Do Vercel Cron Jobs retry on failure?

No. Vercel's docs state that it does not retry an invocation if a cron job fails. Delivery is also best effort, so an occasional run never reaches your function, and a scheduled run can occasionally be invoked more than once. Jobs should be idempotent and catch up on missed work.

How often can a Vercel cron job run?

On Hobby, once per day, at any point within the scheduled hour. On Pro and Enterprise, as often as once per minute with per-minute precision. Every plan allows up to 100 cron jobs per project.

How long can a Vercel cron job run?

The same as any Vercel Function, since a cron job is a function invocation. With fluid compute the default is 300 seconds, the maximum is 300 seconds on Hobby and 800 seconds on Pro and Enterprise, with 1800 seconds in beta.

How do I secure a Vercel cron job endpoint?

Set a CRON_SECRET environment variable. Vercel sends it as a Bearer token in the Authorization header, and your handler returns 401 when the header does not match. Each deployment captures the value at build time, so a changed secret takes effect after the next deploy.

How do I run scheduled jobs with retries outside Vercel?

Move the work to a backend that has a scheduler and a queue. With Encore, a CronJob declared in TypeScript or Go calls an endpoint on schedule, that endpoint publishes one Pub/Sub message per unit of work, and subscriptions retry failed messages with backoff before sending them to a dead-letter queue, on AWS or GCP in your own account.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders