Cron Scheduling

Concept of the skill

What it is: Cron scheduling is the backend discipline of starting recurring work on a time-based schedule while making the resulting execution safe, observable, and recoverable.

Mental model: A schedule expression only creates an alarm. Production scheduling also needs an authenticated entrypoint, a durable worker or workflow target, an idempotency key for the scheduled window, overlap prevention, and monitoring that detects missed starts, failed completions, and duplicate invocations.

Why it exists: Time-based jobs fail outside the normal request path. They can run twice, not retry, overlap with themselves, execute in UTC instead of the expected local time, or disappear into logs without alerting. The skill turns those hidden failure modes into explicit design checks.

What it is NOT: It is not general background-job queue design, event-schema design, webhook ingestion, browser live-update transport, or debugging an isolated worker failure. It owns the schedule-trigger boundary and composes with those skills after work is triggered.

Adjacent concepts: Background jobs, durable workflows, observability, webhook integration, distributed locks, idempotency, and retry classification.

One-line analogy: Cron scheduling is an alarm clock wired to a factory: the alarm rings, but the factory still needs a work order, lock, status board, and missed-alarm monitor.

Common misconception: The common mistake is believing the cron expression is the design. The expression is only the trigger; the production design is the reliability envelope around the trigger.

Cron Scheduling

Domain Context

What is this skill? This skill provides cron job architecture patterns for web applications: Inngest schedule integration, Vercel Cron configuration, retry logic, monitoring and alerting for failed crons, and idempotency requirements. Load when designing scheduled tasks, configuring cron triggers, debugging missed or duplicate executions, or implementing monitoring for recurring jobs.

A cron that runs twice is worse than a cron that doesn't run. Idempotency is not optional.

Coverage

This skill covers cron expression syntax and scheduling precision, Vercel Cron configuration (vercel.json cron routes), Inngest scheduled function patterns (cron triggers vs event-driven), idempotency guarantees for scheduled jobs, retry and failure handling for cron-triggered work, monitoring and alerting for missed or failed cron executions, timezone handling in cron schedules, and the decision framework for choosing between Vercel Cron, Inngest schedules, and external cron services.

Philosophy of the skill

Cron jobs are the most deceptively simple infrastructure in web applications. The expression 0 9 * * * looks trivial, but the implementation must handle: what happens when the job runs twice (deploy overlap), what happens when the job fails silently (no monitoring), what happens when the job takes longer than the interval (overlap), and what happens at DST transitions (timezone drift). Every anti-pattern in this skill was observed in production. The skill exists because agents routinely create cron schedules without idempotency, without monitoring, and without considering the failure modes that only surface under real-world conditions.

Architecture

Cron Platform Decision Matrix

Key architectural rule: Vercel Cron should trigger work, not perform work. The cron route should dispatch an Inngest event or enqueue a background job, then return 200 immediately. Never put long-running logic directly in a Vercel Cron handler.

Vercel Cron Configuration

// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/daily-digest",
      "schedule": "0 9 * * *"
    },
    {
      "path": "/api/cron/sync-orders",
      "schedule": "*/15 * * * *"
    }
  ]
}

Security: When the project defines CRON_SECRET, Vercel sends it as an Authorization header with a Bearer prefix. Always verify that header in the route handler to prevent unauthorized execution:

// api/cron/daily-digest/route.ts
export async function GET(request: Request) {
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // Dispatch work, do not perform work here
  await inngest.send({ name: 'cron/daily-digest.triggered' });
  return new Response('OK', { status: 200 });
}

Inngest Scheduled Functions

// Inngest cron function — preferred for complex scheduled work
import { cron } from "inngest";

export const dailyDigest = inngest.createFunction(
  {
    id: 'daily-digest',
    retries: 3,
    concurrency: { limit: 1 }, // Prevent overlap
    triggers: [cron('TZ=UTC 0 9 * * *')],
  },
  async ({ step }) => {
    const orgs = await step.run('fetch-orgs', async () => {
      return db.query('SELECT id FROM organizations WHERE digest_enabled = true');
    });
    for (const org of orgs) {
      await step.run(`send-digest-${org.id}`, async () => {
        return sendDigestEmail(org.id);
      });
    }
  }
);

Implementation Patterns

1. Idempotency for Cron Jobs

Every cron job must be idempotent: running it twice with the same inputs produces the same result. This is not defensive programming; it is a hard requirement because:

• Vercel may invoke a cron route during overlapping deployments
• Inngest retries failed steps automatically
• Manual re-runs during debugging are common

Pattern: Use an idempotency key based on the scheduled execution window:

const idempotencyKey = `digest-${orgId}-${format(new Date(), 'yyyy-MM-dd')}`;
const existing = await db.query(
  'SELECT 1 FROM cron_executions WHERE idempotency_key = $1',
  [idempotencyKey]
);
if (existing.rows.length > 0) {
  return { skipped: true, reason: 'already executed' };
}
// Execute, then record
await db.query(
  'INSERT INTO cron_executions (idempotency_key, executed_at) VALUES ($1, NOW())',
  [idempotencyKey]
);

2. Cron Expression Reference

Timezone rule: Vercel Cron schedules are UTC. Inngest cron triggers support an optional TZ=<zone> prefix. If the user expects "9am Eastern", either use a scheduler that supports the intended timezone or compute the UTC offset and account for DST transitions. Document the intended local time next to every cron expression.

3. Monitoring and Alerting

A cron job that fails silently is worse than no cron job. Implement monitoring at three levels:

Heartbeat pattern: After each successful cron execution, ping an external heartbeat monitor (e.g., Cronitor, Better Uptime, or a custom endpoint). If the heartbeat is missed, the monitor alerts the team.

// After successful cron execution
await fetch(`${process.env.HEARTBEAT_URL}/cron-daily-digest`, {
  method: 'POST',
  body: JSON.stringify({ status: 'ok', processedCount: orgs.length }),
});

4. Overlap Prevention

When a cron job takes longer than its interval (e.g., a 15-minute sync that runs every 10 minutes), overlapping executions corrupt data or cause duplicate processing.

Solutions:

• Inngest concurrency limit: Set concurrency: { limit: 1 } on the function
• Database lock: Acquire an advisory lock at the start; skip if already held
• Execution record: Check if a previous run is still in-progress before starting

5. Graceful Degradation

When a cron job fails, it must:

1. Log the failure with structured context (job name, execution window, error)
2. Retry with exponential backoff (Inngest does this automatically)
3. After max retries, alert the team and record the failure
4. Never leave the system in a partial state — use transactions for atomicity

Anti-Patterns

1. Long-running logic in Vercel Cron handlers. Vercel Cron routes have a 60s (Hobby) or 300s (Pro) timeout. Put the work in an Inngest function or background job; the cron route should only trigger.

2. No idempotency. A cron that sends duplicate digest emails or double-processes orders because it ran twice during a deploy. Every cron must handle re-execution gracefully.

3. Silent failures. A cron that catches all errors and returns 200. Failed crons must surface errors through logging and alerting, not swallow them.

4. Missing timezone documentation. A cron expression 0 9 * * * without a comment explaining the intended local time. When DST shifts, 9am UTC becomes 4am or 5am Eastern, surprising the user.

5. No overlap protection. A data sync cron that runs every 5 minutes but occasionally takes 8 minutes, causing two instances to process the same data concurrently.

6. Cron for real-time needs. Using a 1-minute cron to poll for new orders instead of using webhooks. Cron is for periodic batch work, not real-time data ingestion.

Key Files

When working in a project with cron scheduling:

• vercel.json — Vercel Cron route definitions
• api/cron/ or app/api/cron/ — Cron route handlers
• Inngest function definitions — for cron-triggered step functions
• cron_executions table (if it exists) — idempotency tracking
• Monitoring service configuration — heartbeat endpoints

Verification

After applying this skill, verify:

• Every cron handler verifies the CRON_SECRET authorization header
• Every cron job is idempotent (safe to run twice)
• Vercel Cron routes dispatch work rather than performing long-running operations
• Overlap prevention is configured for jobs that could exceed their interval
• Monitoring alerts exist for missed or failed executions
• Timezone is documented as a comment next to every cron expression
• Retry logic exists for transient failures

Do NOT Use When

Version 1.0.0 -- 2026-03-29. Initial creation.