Railway change

Railway stops reading railway.json and railway.toml on December 1, 2026: migrate to .railway/railway.ts with railway config migrate

By Ohad Krispin, founder of VibeRaven · LinkedIn

Railway stops reading railway.json and railway.toml on December 1, 2026, the hard cutoff its docs give for Config as Code, which is deprecated in favor of Infrastructure as Code in .railway/railway.ts. Railway's docs say the file overrides the dashboard and the dashboard is never updated from it, so a start command, health check or pre-deploy migration set only in the file stops applying once Railway stops reading it. Migrate with the Railway CLI: railway config migrate previews the generated .railway/railway.ts, --apply writes it, railway config migrate cutover switches the services off Config as Code, and railway config plan and railway config apply push the configuration to Railway. Railway does not read .railway/ during deploys, so the file takes effect only when you apply it, from your terminal or CI. Checked against Railway's docs, changelog and CLI 5.71.0 on 2026-10-25.

Another hosting deadline that breaks builds with no code change is Vercel's Node.js 20 end of support.

What changes on December 1, 2026

Railway announced on August 20, 2026 that Config as Code is going away for its new Infrastructure as Code SDK. From August 28, services in new projects were no longer deployed with Config as Code. Existing railway.json and railway.toml files keep working for the services that already use them until December 1, 2026. Railway's changelog said new services in existing projects should be fine; its docs, read on 2026-10-25, say new services cannot opt into Config as Code.

Why a service can deploy with other settings after the cutoff

Config as Code holds everything in the build and deploy sections of a service's settings: the builder, build command, pre-deploy command, start command, health check path and timeout, and restart policy. Railway's docs say the settings in the dashboard are not updated with the settings in the file, and the file always overrides the dashboard. Once Railway stops reading the file, nothing overrides the dashboard, which may hold old values or defaults. Compare each service's dashboard settings with its file before December 1, or migrate.

Migrate with railway config migrate

railway config migrate finds every railway.json and railway.toml in the repository, including monorepo packages, and writes one .railway/railway.ts; --service <name> migrates one service and writes a named partial export, and --lang py or --lang go writes the beta Python or Go file. Since the CLI change of October 16, 2026, --apply only writes the file: CLI 5.71.0 says services keep reading Config as Code until you run railway config migrate cutover, which lists the affected services, warns about redeploys and saves the old config-file paths. railway config migrate status shows which services still read Config as Code, and railway config migrate undo restores the saved paths. --delete-files deletes the old files from disk, and the CLI says to push that deletion only after cutover, because Railway reads the files until then.

CLI 5.71.0 also asked for --variables=managed or --variables=unmanaged before it did anything else; its help says the flag sets who owns service variables. Railway's IaC docs page, read the same day, does not list that flag and still says --apply clears the Config File settings; the CLI help and the October 16 changelog are newer.

railway login
railway link
railway config migrate
railway config migrate --apply
railway config migrate cutover
railway config migrate status
railway config plan
railway config apply

Plan and apply, and why a push does not deploy the file

railway config plan compares .railway/railway.ts with the linked environment and changes nothing. railway config apply runs a fresh plan and asks you to confirm; deletes of services or variables are marked, and in a non-interactive or agent session they also need --confirm-destructive. Install the SDK with npm install railway so the CLI can evaluate the TypeScript file. Railway does not read .railway/ during deploys, so pushing the file changes nothing until someone applies it; for that from GitHub, Railway publishes the railwayapp/config action, which plans on pull requests and applies the reviewed plan on merge.

A service cannot be managed by both systems: railway config plan stops on a service that still uses railway.json or railway.toml. In a monorepo, migrate writes every service into one file, and leaving a resource out of that file later deletes it on apply. When each service has its own repository, run migrate in each one; each file then exports a partial name and owns only its own services.

Checklist

Before December 1, 2026

Find the Config as Code files in the repository:

git ls-files | grep -E "(^|/)railway\.(json|toml)$"

02Note each service's custom config file path in its Settings; the cutover clears it, and a manual move needs you to clear it yourself.
03Update the CLI with railway upgrade, then link the directory to the project and environment.
04Run railway config migrate, read the generated .railway/railway.ts, then run it again with --apply.
05Run railway config migrate cutover, then railway config migrate status until no service reads Config as Code.
06Run railway config plan. Apply only when it lists the settings you moved and no unexpected deletes.
07After the cutover, delete railway.json and railway.toml from the repository, and run railway config plan in CI if you deploy from GitHub.

Sources

Official docs behind this checklist

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Does pushing .railway/railway.ts deploy the new settings?

No. Railway says it does not read .railway/ during deploys. The settings change when you run railway config apply, or when the railwayapp/config GitHub Action applies a reviewed plan on merge.

Can I keep railway.json and add railway.ts for other settings?

Not for the same service. A service cannot be managed by both, and railway config plan stops on one that still uses the file.

Can I write the file in Python or Go?

Yes, in beta: .railway/railway.py and .railway/railway.go. TypeScript is generally available. Keep only one of the three files.