denoland/deno · error · TypeError

Cannot create cron job, a unique name is required: received

Error message

Cannot create cron job, a unique name is required: received 'undefined'

What it means

Deno.cron(name, schedule, handlerOrOptions?, handler2?) requires a unique job name as the first argument; the name identifies the job across process restarts. An undefined name throws before anything else is validated.

Source

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

    return formatToCronSchedule(minute) +
      " " + formatToCronSchedule(hour) +
      " " + formatToCronSchedule(dayOfMonth) +
      " " + formatToCronSchedule(month) +
      " " + formatToCronSchedule(dayOfWeek);
  }
}

function cron(
  name: string,
  schedule: string | Deno.CronSchedule,
  handlerOrOptions1:
    | (() => Promise<void> | void)
    | ({ backoffSchedule?: number[]; signal?: AbortSignal }),
  handler2?: () => Promise<void> | void,
) {
  if (name === undefined) {
    throw new TypeError(
      "Cannot create cron job, a unique name is required: received 'undefined'",
    );
  }
  if (schedule === undefined) {
    throw new TypeError(
      "Cannot create cron job, a schedule is required: received 'undefined'",
    );
  }

  schedule = parseScheduleToString(schedule);

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

  if (typeof handlerOrOptions1 === "function") {
    handler = handlerOrOptions1;

View on GitHub (pinned to 89f33cbef2)

Solutions

Pass a stable unique string: Deno.cron('nightly-cleanup', '* * * * *', fn).
Validate config at load time: if (!name) throw with a message naming the missing key.

Example fix

// before
Deno.cron(cfg.jobName, '* * * * *', fn); // cfg.jobName is undefined
// after
if (!cfg.jobName) throw new Error('cron job requires cfg.jobName');
Deno.cron(cfg.jobName, '* * * * *', fn);

Defensive patterns

Strategy: validation

Validate before calling

if (typeof name !== 'string' || name.length === 0) {
  throw new Error('cron job name is required');
}
Deno.cron(name, schedule, handler);

Type guard

function isCronName(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}

Prevention

Validate cron job config (name, schedule) at config-load time with clear messages.
Keep the (name, schedule, handler) order explicit; avoid positional spreads into Deno.cron.

When it happens

Trigger: Deno.cron(undefined as any, '* * * * *', fn); swapping argument order (schedule first); spreading a config object whose name key is missing.

Common situations: Dynamic job registration from configuration or CLI flags where the name was never set.

Related errors

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