Automation troubleshooting
Use this page for scheduler and delivery issues (cron + heartbeat).
Command ladder
Cron not firing
cron statusreports enabled and a futurenextWakeAtMs.- Job is enabled and has a valid schedule/timezone.
cron runsshowsokor explicit skip reason.
cron: scheduler disabled; jobs will not run automatically→ cron disabled in config/env.[cron] failed to start: value "..." is out of range for type integer→ Postgrescron_jobsstill has 32-bitintegeron an epoch-ms column. Restart on a build that widens those columns toBIGINT. See Where cron jobs are stored.cron: timer tick failed→ scheduler tick crashed; inspect surrounding stack/log context.reason: not-duein run output →wednesdayai cron run <jobId> --dueor Web UI Run if due was used and the job is not due yet.main job requires payload.kind="systemEvent"→ the job is stored as a main-session job with an incompatible payload. Use the Web UI Timeline message or Check first, then nudge job type, or recreate the job with a matchingsessionTarget/payload.kind.isolated job requires payload.kind=agentTurn→ the job is stored as an isolated job without an assistant-task payload. Use the Web UI Assistant task job type or recreate the job with--session isolated --message ....wake-gate-empty→ the job-level wake-gate check ran and found no work. This is a valid skipped result, not a scheduler failure. A main-session Timeline message (wakeMode=now) must not inherit this fromheartbeat.wakeGate. If a due main cron is skipped aswake-gate-empty, the job itself has a wake-gate payload — it is not waiting on the periodic heartbeat email-gate.main cron enqueueAgentTurn not wired→ the Gateway is an older build without the agent-turn producer wiring. Restart on a build that includes H2 (enqueueAgentTurnon CronService).already runningoralready-running→ the previous run or target lane is still active. Wait for it to finish, then inspectwednesdayai cron runs --id <jobId> --limit 20.cron: disabled job <id>: malformed payload_json(orschedule_json) → the stored job was unreadable and was disabled on load. See A job turned itself off.
Cron fired but no delivery
- Run status is
ok. - Delivery mode/target are set for isolated jobs.
- Channel probe reports target channel connected.
- Run succeeded but delivery mode is
none→ no external message is expected. - Delivery target missing/invalid (
channel/to) → run may succeed internally but skip outbound. - Channel auth errors (
unauthorized,missing_scope,Forbidden) → delivery blocked by channel credentials/permissions. - Web UI shows
Not deliveredon an internal run → delivery was not requested. Set result delivery toannounceorwebhookwhen you expect an outbound message. cron: dropped malformed delivery_json on job <id>→ the stored delivery settings were unreadable and were dropped. Set them again withwednesdayai cron edit <jobId>.
Heartbeat suppressed or skipped
- Heartbeat enabled with non-zero interval.
- Last heartbeat result is
ran(or skip reason is understood).
heartbeat skippedwithreason=quiet-hours→ outsideactiveHours.requests-in-flight→ main lane busy; heartbeat deferred.empty-heartbeat-file→ interval heartbeat skipped becauseHEARTBEAT.mdhas no actionable content and no tagged cron event is queued.alerts-disabled→ visibility settings suppress outbound heartbeat messages.
Timezone and activeHours gotchas
Config path not found: agents.defaults.userTimezonemeans the key is unset; heartbeat falls back to host timezone (oractiveHours.timezoneif set).- Cron without
--tzuses gateway host timezone. - Heartbeat
activeHoursuses configured timezone resolution (user,local, or explicit IANA tz). - ISO timestamps without timezone are treated as UTC for cron
atschedules.
- Jobs run at the wrong wall-clock time after host timezone changes.
- Heartbeat always skipped during your daytime because
activeHours.timezoneis wrong.