iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To find why a pg_cron job failed—and tell a retry from a later scheduled run—capture execution-level records and correlate them with PostgreSQL logs. Keep three identities separate: the job is its schedule and definition, a run is one execution, and a background worker is a PostgreSQL process involved in scheduling or executing work. pg_cron does not document a built-in cohort field, so cohort and retry identifiers must come from your application or a durable run record.
What does a pg_cron worker error mean?
A message about a worker is not enough to establish that a scheduled SQL command ran, failed, or was retried. pg_cron runs inside PostgreSQL and uses a background worker to track scheduled-job metadata; depending on configuration, it connects to PostgreSQL or starts a database worker to execute a job. A process restart and a SQL execution are different events.
Likewise, a job definition is not an individual execution. A scheduled job can have many runs, and a later cron firing is not automatically a retry of an earlier failed run. To diagnose a failure, identify the job and the specific run, then correlate that run’s timing and error with server logs.
How do I find why a pg_cron job failed?
Start with the run record
pg_cron documents cron.job_run_details as its run-history table. The cron.log_run setting controls whether run details are logged there and is documented as defaulting to on; deployments can change configuration. Check the installed extension version, setting, and actual table columns before relying on a particular query or schema.
#1 Best Overall
For each execution, preserve the job identifier, run identifier, start and end times, status, and any returned error information available in your installation. These fields let you distinguish separate executions of one job and create a timeline to compare with PostgreSQL server logs. Keep records for long enough to cover the investigation and any delayed retries your application may perform.
Check server logs when the run table is not enough
A run record may show that an execution did not succeed without explaining whether the cause was a SQL error, a connection or startup problem, or a broader scheduler or server issue. Inspect PostgreSQL logs around the run’s timestamps for relevant ERROR, FATAL, or PANIC messages. If a scheduled function needs to expose application context, add deliberate log messages inside that function, taking care not to log secrets or sensitive data.
Rank #2
Use provider guidance in its service context
Supabase’s troubleshooting guide recommends checking pg_stat_activity for the pg_cron scheduler, reviewing non-succeeded and non-running entries in cron.job_run_details, considering concurrent job load and database strain, and inspecting PostgreSQL logs when run records do not explain the problem. These are useful Supabase operational steps, not universal recovery guarantees for every PostgreSQL host.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does PostgreSQL automatically retry a failed cron job?
Do not infer an automatic retry from a worker restart or from seeing another run. The pg_cron documentation describes what happens when triggers overlap: different jobs may run in parallel, but only one instance of a particular job runs at a time. If another trigger arrives while that job is active, it is queued until the active instance finishes. Queueing an overlapping trigger is not the same as retrying a failed SQL command.
PostgreSQL’s background-worker setting bgw_restart_time specifies a restart interval for a registered worker after a crash, or may be set to BGW_NEVER_RESTART. That process-lifecycle behavior does not determine whether an application-level command is retried, nor whether repeating its side effects is safe. Check the actual retry wrapper, scheduler configuration, and function behavior in your deployment before claiming a retry policy.
How can I tell which retry or cohort produced an error?
Use a stable application-level cohort key and retry or attempt identifier in addition to pg_cron’s job and run identifiers. Store or log them together with timestamps and the outcome of the logical work item. pg_cron documents job and run capture, but the reviewed documentation does not describe a native cohort field.
Rank #4
- HP ProLiant DL360 G7 8B Server
- 2x X5650 2.66GHz 12-Cores Total
- 32GB RAM / 8x 146GB 10K 2.5in SAS Hard Drives
- P410 w/ 512MB
A useful record should make it possible to distinguish these cases:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →- The same logical work item was attempted again: its cohort or work-item key stays stable while the attempt identifier changes.
- Different members of a cohort failed independently: each has its own work-item identity, even if they share the cohort key.
- A normal future schedule fired: it has a new pg_cron run, but should not be labeled a retry unless the application links it to the same logical work item.
- A scheduler or worker outage occurred: process and server logs may show it, but it does not by itself prove that a particular SQL command ran or that its effects were repeated.
Use identifiers that remain stable across the retry boundary. If retries are implemented by a function, queue, or external orchestrator, have that component record the attempt and logical work-item identity durably; then correlate those records with the pg_cron run and server-log timeline.
Quick Recap
Which evidence source answers which question?
| Evidence | What it identifies | What it can reveal | Context and limits |
|---|---|---|---|
cron.job |
A job definition | The scheduled job to investigate | It is not an individual execution record and does not supply application cohort identity. |
cron.job_run_details |
An individual execution | Run status, timing, and available error information | Capture depends on cron.log_run; confirm installed columns and configuration. |
| PostgreSQL server logs | Server and process events around a time | Errors that may clarify SQL, connection, startup, or server-level failures | Correlate log timestamps with the job run; application-specific cohort context may require custom messages. |
| Application retry or durable work-item records | Logical work item, cohort, and attempt | Whether a repeated attempt belongs to the same work item | The identifiers and retention are implementation-specific; pg_cron does not document a built-in cohort field. |
pg_stat_activity in Supabase troubleshooting |
Current database activity, including the scheduler process | Whether the scheduler appears active at inspection time | This diagnostic is recommended by Supabase; a current activity snapshot is not a history of prior executions. |
Build a failure timeline without confusing runs
- Confirm the installed setup. Check the pg_cron version,
cron.log_runvalue, actual run-table columns, host or provider, and the mechanism that performs retries. - Identify the scheduled job. Find the relevant job definition in
cron.joband note its identifier and schedule. - Choose the failed execution. Use
cron.job_run_detailsto record its run identifier, start and end times, status, and available error text. - Correlate by time. Inspect PostgreSQL server logs around that execution. For Supabase, also follow its guidance to inspect scheduler activity, run records, concurrent load, and database strain.
- Link application identity. Match the execution to the durable cohort, work-item, and attempt identifiers recorded by the retry implementation.
- Classify what happened. Separate SQL failure, a later scheduled firing, an application retry, and a scheduler or worker process problem. Do not label one as another without linked execution evidence.
What to verify before relying on a failure query
- Confirm the installed pg_cron version and configuration rather than assuming documented defaults apply to your deployment.
- Check the real columns in
cron.job_run_detailsbefore using a query written for another version or host. - Verify whether run logging is enabled and whether records remain available for the time window under investigation.
- Trace retry behavior in the actual wrapper or application code; a subsequent scheduled run alone is not proof of a retry.
- Ensure retryable work is safe to repeat or protected by application-level idempotency. Worker restart configuration does not provide that guarantee.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
