Troubleshooting

Tasks never run

Registering @quik/scheduler in bootstrap is not enough. The module only initializes the IQScheduleExecutor and IQBackgroundRunner features when the bootstrap startScheduler flag is set (options.flags.startScheduler). Without it, registerTask() is a no-op and getTaskScheduler() throws because no IQScheduleExecutor feature is registered.

Task registered but not scheduled

registerTask(...) only adds task instances to the executor's list — it does not (re)start the cron jobs. Call getTaskScheduler().start(), or reloadScheduler() to stop and restart both the executor and the background runner, so newly registered tasks pick up their schedule.

Task runs are being skipped

When scheduler.maxConcurrency (default 1) is reached for a task, subsequent scheduled runs are skipped and a drift warning is logged instead of queued. Raise SCHEDULER_MAX_CONCURRENCY if overlapping runs are expected.

Database executor did not load

Setting scheduler.executor.database only switches to the database-backed executor if @quik/database is also registered in bootstrap. If loading QDBExecutor fails (missing dependency, misconfiguration), the module logs an error and falls back to the in-memory QExecutor rather than throwing.

Invalid execution plan values

Building a cron expression from an IQExecutionPlan throws a plain QError (from @quik/core) when months, days, hours, minutes, or weekdays contain out-of-range values, or when a day would never occur in the given month (e.g. day 31 in April, or day 30+ in February).

Common Errors

@quik/scheduler has no locale file of its own — invalid execution plan values raise plain QError instances (see above) rather than translated quik.errors.scheduler.* keys.