Settings — Scheduler

The Scheduler page is where every recurring job in Sublarr lives. It’s the operations console: see when each job last ran, when it’ll next fire, whether it succeeded, and force a run-now or pause without restarting the container. Backed by APScheduler with a SQLAlchemy job store, so jobs survive restarts with their next-fire-time intact.

What’s listed

The page shows one row per registered job. Six jobs ship out of the box:

Job	Default trigger	Effect
wanted_scanner	every 6 h	Walks the library, queues searches for items missing target language.
wanted_search	every 4 h	Processes the wanted queue (provider calls).
cleanup	nightly 03:00	Runs cleanup rules: orphan delete, format upgrades, trash prune.
upgrade_scan	every 24 h	Scans for upgrade candidates against existing subtitles.
anidb_sync	every 30 days	Refreshes the offline AniDB dump.
scheduler_history_cleanup	nightly 04:00	Prunes scheduler history older than the configured retention.

Plugins can register their own jobs; those appear in the list with a plugin:<name>: prefix on the job ID.

Per-row controls

Column	Effect
Job ID	Unique identifier. Human-readable for built-in jobs.
Trigger	Current trigger expression — interval (every 6h) or cron (0 3 * * *). Edit inline.
Last run	Timestamp + outcome (ok / failed / skipped_overlap).
Next run	When the next firing is scheduled.
Runtime (avg)	Median wall-clock time over the last 30 runs.
Run now	Triggers the job out-of-band. Respects per-job concurrency lock.
Pause	Suspends future firings without removing the job.
Edit trigger	Open the trigger editor — interval or cron.
History	Drawer with the last 100 runs and their outcomes.
Reset to default	Restore the trigger to the shipped default. Useful if a custom edit is causing issues.

Trigger types

Type	Editor field	Example
Interval	hours / minutes / seconds	every 6h (every 6 hours)
Cron	minute, hour, day, month, day-of-week	0 3 * * * (3:00 AM daily)

Cron is preferred for “fire at a specific time of day” jobs (cleanup, anidb_sync). Interval is preferred for “fire every X” jobs (scanners, queue drains).

Run-now semantics

Clicking Run now:

1. Queues an immediate firing — bypasses the next scheduled time.
2. Acquires the per-job lock — if a scheduled run is currently in-flight, the run-now waits.
3. Records the run as manual: true in history so you can distinguish from scheduled firings.

If a manual run-now collides with a scheduled tick, the second-arriving fire is recorded as skipped_overlap and not run twice.

Pause / resume

Pausing keeps the job in the registry but skips firings until resumed. Useful for:

Scenario	Action
Maintenance window — don’t run the scanner	Pause wanted_scanner until done.
Provider rate-limit incident	Pause everything that calls providers.
Investigating a misbehaving job	Pause to observe state without further triggering.

Paused jobs show a paused badge; their Next run is replaced with paused.

Job history

The History drawer shows recent runs with full timing breakdown:

Column	Effect
Started at	When the run began.
Finished at	When the run ended (or running if in-flight).
Duration	Wall-clock time.
Outcome	ok / failed / cancelled / skipped_overlap.
Items processed	Count of meaningful work units (varies per job).
Error	Truncated stack trace on failure; click for full.

Per-job retention is configured via the scheduler_history_cleanup job (default 30 days).

Single-instance enforcement

Sublarr is designed to run as a single primary instance. Running multiple replicas with the same database would cause every job to fire on every replica.

Set SUBLARR_SCHEDULER_ROLE=disabled on all replicas except the primary to prevent duplicate firings. The primary defaults to primary.

Value	Behaviour
primary (default)	Scheduler runs.
disabled	Scheduler is suspended; replica only serves API/UI traffic.
anything else	Startup raises an error.

Custom jobs

Plugins or operators with API access can register custom jobs via POST /api/v1/scheduler/jobs. Custom jobs require a Python callable resolvable at the configured module path; see Plugin Development for the registration pattern.

Health surface

The header shows aggregate health:

Tile	Meaning
Total jobs	Registered jobs (built-in + plugin).
Active	Not paused, not in-flight.
Running	Currently firing.
Failed (last 24h)	Jobs with at least one failure in the last day.

Three or more failures in a row on the same job triggers the scheduler_job_failed notification event.