The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →To trace a pg_cron failure across retries and cohorts, capture each scheduled execution separately and add your application’s cohort key and attempt identifier to a durable record or log. A pg_cron job is the schedule definition; a run is one execution; a PostgreSQL background worker is a process that may schedule or execute work. Those are different things, and a worker restart or a later scheduled firing does not prove that a failed SQL command was retried.
What exactly failed: the job, a run, or a worker?
Use the right identity before building a failure timeline. pg_cron stores scheduled job definitions in cron.job. Each time a scheduled command executes, that is a run. Separately, PostgreSQL may use a background worker to track scheduled jobs or execute them, depending on pg_cron’s configuration.
As an Amazon Associate I earn from qualifying purchases.
- Job: the recurring schedule and command definition.
- Run: one execution of that command, with its own timing and outcome.
- Worker: a PostgreSQL process involved in scheduling or executing work. A worker’s lifecycle is not the same as the SQL command’s outcome.
This distinction matters when interpreting logs: a worker crash can disrupt scheduling or execution, while a run record can show a command failure. A later run may simply be the next scheduled firing rather than a retry of the earlier run.
Does pg_cron automatically retry a failed command?
The documented concurrency behavior is not an automatic retry policy. pg_cron can run different jobs in parallel, but only one instance of a particular job runs at a time. If another firing arrives while that job is active, it is queued until the active run finishes. That queueing rule addresses overlap; it does not establish that a failed command will be re-executed.
#1 Best Overall
To establish whether your application retries a failed run, inspect the retry wrapper or orchestration code and its durable attempt records. Do not infer a retry from a subsequent run with the same job ID or from a restarted worker.
Where are pg_cron run errors recorded?
The pg_cron project documents cron.job_run_details for run history and the cron.log_run setting for enabling run-detail logging. The documented default for cron.log_run is on, but deployments can change configuration. The project also documents cron.max_running_jobs with a default of 32; that is a configurable default, not a guarantee about a specific server’s capacity.
Rank #2
Start by checking the installed extension version, the setting, and the actual table definition. Available columns and error details depend on the installed version and deployment, so verify them before using a query copied from elsewhere.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFor each execution, preserve whatever your installation exposes for:
- the scheduler job identifier and run identifier;
- start and end timestamps;
- the run status and returned error information;
- the application cohort key and retry or attempt identifier.
The scheduler’s run history can help identify the job and execution timing, but the reviewed pg_cron documentation does not describe a built-in cohort field. Add cohort and attempt context in application-level logging or a durable application-owned run table, then correlate it with scheduler records.
How do I find why a pg_cron job failed?
- Check the job definition. Inspect
cron.jobto confirm which command and schedule correspond to the affected job. - Find the individual execution. Review
cron.job_run_detailsfor the relevant job and time window. Use the installed schema’s actual column names and status values, and retain the run ID and timestamps. - Check scheduler activity. On Supabase, its troubleshooting guide recommends checking
pg_stat_activityfor thepg_cron scheduler. This is provider-specific guidance, not a universal PostgreSQL recovery procedure. - Inspect PostgreSQL server logs. If the run record does not explain the failure, look for related
ERROR,FATAL, orPANICmessages around the run’s timestamps. The run table may not contain enough information to diagnose connection, startup, or broader server problems. - Consider contention and load. Check whether other jobs or database strain could have delayed or prevented execution. Supabase’s guide includes concurrent job load among its troubleshooting checks.
- Add application context where needed. If the scheduler record cannot identify which cohort member or retry attempt was involved, log a stable cohort key and attempt ID inside the function or in a durable application-owned record.
Supabase’s advice applies to its managed service context; its extension-version statements and recovery steps should not be generalized to every PostgreSQL installation. For any deployment, correlate run records with the server logs available to that operator.
How can I distinguish a retry from a new scheduled run?
Record both scheduler identity and application identity. The scheduler job and run IDs locate a definition and execution; your application’s cohort key and attempt ID identify the logical work item and the attempt made on its behalf. Together, they let you distinguish cases that otherwise look alike:
Free tools Windows power users keep installed
One-click scans. No signup required.
- Same work item, another attempt: the cohort key stays stable while the application attempt identifier changes.
- Different cohort members: each work item has its own cohort key, even when both fail under the same scheduled job.
- Ordinary later firing: a new scheduler run occurs, but there is no evidence it represents another attempt at the earlier logical work item unless the application records that relationship.
- Scheduler or worker disruption: process or server logs show a lifecycle or availability issue; that alone does not establish that a SQL transaction was retried.
This scheme is an implementation recommendation, not a native pg_cron cohort feature. Make identifiers stable across retries and retain timestamps so records can be correlated even when the scheduler and application logs are stored separately.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What does a background-worker restart tell you?
PostgreSQL’s background-worker registration includes bgw_restart_time, which controls the interval before a crashed registered worker is restarted, or can be set to BGW_NEVER_RESTART. This setting concerns the process lifecycle. It does not specify whether a scheduled SQL command is retried, whether a transaction committed, or whether repeating its side effects is safe.
For retry behavior, inspect the application’s retry mechanism and the command’s transaction and side-effect handling. Treat worker restart evidence and execution outcome evidence as separate parts of the timeline.
Quick Recap
Which evidence source should you use?
| Evidence source | What it identifies | What it can help reveal | Context and limits |
|---|---|---|---|
cron.job |
Job definition | Which scheduled command and schedule are involved | Does not by itself identify an individual run’s outcome |
cron.job_run_details and cron.log_run |
Individual execution | Run timing, status, and error information available in the installed deployment | Check installed version, configuration, and actual columns; does not inherently provide application cohort context |
| PostgreSQL server logs | Server and process events around execution | Errors or failures not explained by run records, including connection or broader server issues | Available detail depends on deployment logging and access |
| Application-owned run records or logs | Logical work item and attempt | Which cohort member and retry attempt produced an error | Requires the application to record stable identifiers and correlate them with scheduler runs |
| Worker registration and lifecycle evidence | Background-worker process | Whether PostgreSQL is configured to restart a crashed registered worker | Does not establish SQL retry behavior or successful replay |
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.
