Railway cron job not running? Find the cause and get alerted
A Railway cron job that gets skipped leaves no error behind, only a gap between runs. Here is how to find the cause and get an alert the next time a run is missed.
Updated
Short answer
Railway skips a scheduled run if the previous run is still going, so a service that does not exit blocks every run after it. Schedules are in UTC, runs must be at least 5 minutes apart, and start times can drift by a few minutes. Ping a heartbeat URL at the end of the job and alert when it stops arriving.
Monitor your Railway cron jobs freeWhy Railway cron jobs get skipped
You set a cron schedule in the service's Settings, under Cron Schedule. At each scheduled time Railway runs the service's start command. The Railway docs describe these causes when runs do not happen.
| Cause | How to check | Fix |
|---|---|---|
| Previous run still active | railway cron list shows the last run with status Active | Railway skips the new run while the previous one runs, and it does not terminate deployments for you. Make the process exit |
| Process does not exit | The service keeps running after the work is done | Exit as soon as the task is finished and close resources such as database connections, so the process can end |
| Schedule is in UTC | The job fires at an unexpected hour | Convert your local time and check the expression in a cron generator |
| Runs too close together | The schedule has an interval under 5 minutes | Scheduled runs must be at least 5 minutes apart in UTC. An expression like */7 * * * * is invalid because the gap at the hour change is shorter |
| Start time varies | Runs start a few minutes off the schedule | Railway does not guarantee execution times to the minute. Allow for a few minutes in your grace period |
| Wrong kind of workload | The service is a web server or bot | Cron is not suited to long-running processes or to running more often than every 5 minutes |
Check recent runs
Use the Railway CLI to see whether runs are happening and trigger one by hand.
# View recent runs for the service
railway cron list
# Trigger a run outside the schedule
railway cron run- Run
railway cron list. If the most recent run has the statusActive, it is still running and new runs will not start. - If a run stays
Activelong after the work should be done, the process is not exiting. Look for open database pools, timers or listeners that keep it alive. - Check the schedule in Settings against UTC, and against the 5-minute minimum.
- Use
railway cron runto confirm the start command works when triggered by hand.
Make the job exit, then ping a heartbeat
Exiting is the fix for most skipped runs, and it is also the right place for the ping. Send a request to a heartbeat URL as the last step of a successful run. When the ping stops arriving, you are alerted, whether the cause was a skipped run, a crash or a wrong schedule.
import { pool } from './db';
async function main(): Promise<void> {
await runJob();
// Only reached when runJob() did not throw.
await fetch(process.env.HEARTBEAT_URL!, { signal: AbortSignal.timeout(10_000) });
}
main()
.then(async () => {
await pool.end(); // close connections so the process can exit
process.exit(0);
})
.catch((error) => {
console.error('job failed', error);
process.exit(1);
});To ping from a shell instead, put the job and the ping in a script and set the start command to ./scripts/job.sh. set -euo pipefail stops the script at the first failed step, before it pings.
#!/bin/bash
set -euo pipefail
node dist/job.js
curl -fsS -m 10 --retry 3 https://heartbeat.uptimeio.com/heartbeat/YOUR_HEARTBEAT_TOKEN > /dev/nullStore the heartbeat URL as a service variable. It works like a password, so keep it out of the repository.
Set it up in UptimeIO
- Create a monitor and choose the Heartbeat type.
- Set the interval to match the Railway schedule. Add a grace period of at least a few minutes, because Railway start times can vary, plus your slowest run time.
- Copy the heartbeat URL into a service variable or the start command.
- Choose where alerts go: email, Slack, Telegram, Pushover or a webhook.
- Plans: heartbeat monitors are on every plan, including Free. The shortest interval is 5 minutes on Free and 1 minute on Pro and Scale.
- Intervals: 1 minute to 24 hours, with a grace period of 1 second to 24 hours.
- Incidents: an incident opens when a ping is late, and resolves after 3 on-time pings in a row.
Questions
- Why is my Railway cron job not running?
- The usual cause is that the previous run is still active. Railway skips a new scheduled run when the previous one has not finished, and it does not stop deployments for you. Make sure the process exits when its work is done.
- What is the minimum interval for a Railway cron job?
- Scheduled runs must be at least 5 minutes apart in UTC. Railway does not suit jobs that need to run more often than that.
- What time zone does Railway cron use?
- UTC. Convert from your local time when you write the schedule. Railway also notes that execution times can vary by a few minutes.
- How do I see whether a Railway cron job ran?
- Run railway cron list in the CLI to view recent runs, and railway cron run to trigger one outside the schedule. A run with the status Active is still running.
- How do I get an alert when a Railway cron job fails?
- The Railway cron docs do not describe failure notifications. Send a request to a heartbeat URL at the end of the job, only on success, and alert when it does not arrive.
Related
- Cron job monitoring - How UptimeIO heartbeat monitoring works and which plans include it.
- Heartbeat monitoring docs - Settings, ping examples, metadata, and rate limits.
- Render cron job not running - Causes and heartbeat setup for Render cron job services.
- Cron job not running - General causes and the heartbeat pattern for any cron job.