denoland/deno · error · TypeError

Cannot create cron job: a handler is required

Error message

Cannot create cron job: a handler is required

What it means

If neither the third nor the fourth argument to Deno.cron is a function, no handler exists and cron creation throws. The handler is what the scheduler invokes on each tick.

Source

Thrown at ext/cron/01_cron.ts:145

  schedule = parseScheduleToString(schedule);

  let handler: () => Promise<void> | void;
  let options:
    | { backoffSchedule?: number[]; signal?: AbortSignal }
    | undefined = undefined;

  if (typeof handlerOrOptions1 === "function") {
    handler = handlerOrOptions1;
    if (handler2 !== undefined) {
      throw new TypeError(
        "Cannot create cron job, a single handler is required: two handlers were specified",
      );
    }
  } else if (typeof handler2 === "function") {
    handler = handler2;
    options = handlerOrOptions1;
  } else {
    throw new TypeError("Cannot create cron job: a handler is required");
  }

  const rid = op_cron_create(
    name,
    schedule,
    options?.backoffSchedule,
  );

  if (options?.signal) {
    const signal = options?.signal;
    signal.addEventListener(
      "abort",
      () => {
        core.close(rid);
      },
      { once: true },
    );
  }

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Pass the handler function: Deno.cron('n', sched, () => { ... }).
2. With options: Deno.cron('n', sched, { backoffSchedule: [1000] }, handler).
3. Check the handler import resolves: typeof handler === 'function'.

Example fix

// before
Deno.cron('n', '* * * * *');
// after
Deno.cron('n', '* * * * *', async () => {
  await runJob();
});

const handler = typeof handlerOrOptions1 === 'function' ? handlerOrOptions1 : handler2;
if (typeof handler !== 'function') {
  throw new Error('cron job requires a handler function');
}

function isCronHandler(v: unknown): v is () => void | Promise<void> {
  return typeof v === 'function';
}

When it happens

Trigger: Deno.cron('n', '* * * * *') with no third argument; Deno.cron('n', sched, { backoffSchedule: [1000] }) with options but no handler function.

Common situations: Passing options but forgetting the handler; a handler variable that is undefined due to an import or naming mistake.

Related errors

• Invalid cron schedule: start=${start}, end=${end}, every=${e
• Cannot create cron job, a unique name is required: received
• Cannot create cron job, a schedule is required: received 'un
• Cannot create cron job, a single handler is required: two ha
• Delay must be >= 0: received ${delay}

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/674506071562b04c. Report an issue: GitHub.