Scheduler Troubleshooting

This guide covers common scheduler issues and how to resolve them in production.

Architecture

The scheduler uses a Postgres-backed schedule table as the single source of truth. A single scheduler instance polls enabled schedules and dispatches Celery tasks.

Important: Only one scheduler instance should run at a time. This is enforced operationally via deployment configuration (e.g., single replica), not via database locks.

Schedule auto-disable

The scheduler automatically disables schedules that cannot be executed safely.

Symptoms

• Logs show Schedule <id> auto-disabled: <reason>. Manual intervention required.
• The schedule's enabled flag is set to false

Causes

Reason	Description
invalid task_type	The task_type value is not a valid TaskType enum member
task scope mismatch	The schedule scope conflicts with TaskType policy
invalid task_args	The task_args JSON fails ScheduleTaskArgs validation
missing project metadata	A project schedule references a project_id that no longer exists
invalid crontab	The crontab expression cannot be parsed (must be 5 fields)
crontab due check failed	The crontab schedule raised an exception during due-time calculation

Recovery steps

1. Check scheduler logs for the specific reason.
2. Fix the underlying data issue (e.g., correct the crontab, restore the project, or update task_args).
3. Re-enable the schedule via the API or database.

Database connectivity

Symptoms

• Tasks are not being dispatched

Causes

• Postgres is unavailable or restarting
• Network interruptions between scheduler and Postgres
• Migrations have not run (schedule table missing)

Recovery steps

1. Check Postgres connectivity from the scheduler container.
2. Verify migrations have been applied.