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 free

Why 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.

CauseHow to checkFix
Previous run still activerailway cron list shows the last run with status ActiveRailway skips the new run while the previous one runs, and it does not terminate deployments for you. Make the process exit
Process does not exitThe service keeps running after the work is doneExit as soon as the task is finished and close resources such as database connections, so the process can end
Schedule is in UTCThe job fires at an unexpected hourConvert your local time and check the expression in a cron generator
Runs too close togetherThe schedule has an interval under 5 minutesScheduled 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 variesRuns start a few minutes off the scheduleRailway does not guarantee execution times to the minute. Allow for a few minutes in your grace period
Wrong kind of workloadThe service is a web server or botCron 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.

Railway CLIShell
# View recent runs for the service
railway cron list

# Trigger a run outside the schedule
railway cron run
  1. Run railway cron list. If the most recent run has the status Active, it is still running and new runs will not start.
  2. If a run stays Active long after the work should be done, the process is not exiting. Look for open database pools, timers or listeners that keep it alive.
  3. Check the schedule in Settings against UTC, and against the 5-minute minimum.
  4. Use railway cron run to 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.

src/job.tsTypeScript
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.

scripts/job.shShell
#!/bin/bash
set -euo pipefail

node dist/job.js

curl -fsS -m 10 --retry 3 https://heartbeat.uptimeio.com/heartbeat/YOUR_HEARTBEAT_TOKEN > /dev/null

Store the heartbeat URL as a service variable. It works like a password, so keep it out of the repository.

Set it up in UptimeIO

  1. Create a monitor and choose the Heartbeat type.
  2. 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.
  3. Copy the heartbeat URL into a service variable or the start command.
  4. 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 1 hour.
  • 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

Start monitoring in a few minutes

Start monitoring free

Free plan · 50 monitors · No credit card required