Error: Environment variable DATABASE_URL not set – Unresolved per‑project timezone for scheduled tasks

The short answer

Two separate issues are tangled together here. The Environment variable DATABASE_URL not set error is a deployment-time failure: the Railway CLI aborts before your container starts, so no scheduled task can run at all until you define that variable. Separately, Railway's cron scheduler evaluates schedules in UTC. Setting TZ on the service changes the timezone inside the container, but it does not change when the scheduler fires.

Fixing the DATABASE_URL error first

If your project has a Railway Postgres (or other database) plugin, the usual cause is that the service running the scheduled task is not linked to that database, so the variable is never injected. In the Railway dashboard, add a variable reference to the database service's DATABASE_URL, or set the value directly:

railway variables set DATABASE_URL=postgresql://user:pass@host:5432/dbname

Verify it is visible to the service before redeploying:

railway variables | grep DATABASE_URL

Why TZ does not move your cron schedule

Railway's scheduler triggers tasks against UTC. The TZ environment variable is honored by the container runtime — so date and your application's time libraries will report local time — but a cron expression like 0 9 * * * still fires at 09:00 UTC, not 09:00 in America/New_York. This is the platform's documented behavior as of the most recent public docs I can rely on; treat any claim of a per-project scheduler timezone setting as unverified until you see it in the changelog.

Recommended approaches

1. Convert your cron expression to UTC. For a fixed offset this is simple: 09:00 in a UTC+2 zone becomes 0 7 * * *. The catch is daylight saving — the correct UTC time shifts twice a year, so a static expression will drift by an hour.
2. Schedule hourly and gate inside the task. Have the cron fire every hour, then check the local time inside your code (with TZ set, or a library like zoneinfo/luxon) and exit early unless it matches your target window. This handles DST correctly because the conversion happens at runtime.
3. Use an in-process scheduler. Run a long-lived service with a library (for example node-cron with a timezone option, or APScheduler) that interprets schedules in your zone, instead of relying on the platform scheduler.

Database timestamps

Keep storing timestamps in UTC in the database — that is the correct default and most drivers do it automatically. Convert to local time only at the display or scheduling-decision layer. Mixing local-time storage with a UTC scheduler is what produces off-by-one-hour bugs after DST transitions.

Will Railway add a per-project timezone setting?

As of the documentation available up to mid-2024, Railway has not announced a per-project or per-task timezone override for scheduled tasks, and I can't verify anything more recent from here. Check the Railway changelog and the cron/scheduled-tasks docs page for any new setting before designing around this. If a native option appears, prefer it over cron-expression arithmetic, since it will handle DST for you.

Quick verification

Deploy a minimal scheduled task that logs the current time with and without TZ set, then compare the invocation timestamp in the Railway logs against your local wall clock. If the log shows the task firing at the UTC equivalent of your cron expression, the scheduler is UTC-based regardless of TZ — which is the behavior to design around.