Start shipping →

Answers · Deploying

What happens if I lose the Rails master key?

The encrypted credentials are gone. RAILS_MASTER_KEY is the only thing that decrypts config/credentials.yml.enc, and there is no recovery path by design. Delete both files, regenerate them, and re-enter every secret from its source. Production will not boot until the key reaching the server matches the file in the repo.

Updated · 2 min read

Regenerate the pair

The key and the encrypted file are a matched set. A new key cannot read an old file, so both go:

rm config/credentials.yml.enc config/master.key
bin/rails credentials:edit

That opens an editor on a fresh encrypted file and writes a new config/master.key beside it. master.key is gitignored; the .enc file is committed. Commit the new one.

Then re-enter every secret

Nothing is recoverable from the old file, so work from the sources instead. Each service has its own route back:

  • Stripe. Roll the secret key in the dashboard and copy the new one. The old key keeps working until you roll it, so this is safe to do calmly.
  • Resend. Same shape: create a new API key, delete the old one.
  • OAuth. Google and Apple client secrets can be regenerated from their consoles.

docs/BRING_YOUR_OWN_KEYS.md lists every key the app reads and which ones are optional. Most of them are, and an app that only has RAILS_MASTER_KEY still boots and runs on the local fakes.

Get the new key to production

bin/kamal secrets print
bin/kamal deploy

RAILS_MASTER_KEY reaches the server through .kamal/secrets, which is not committed. Update it there, confirm the secrets listing shows a value, then deploy. A deploy with the wrong key fails on the health check, because Rails raises during initialization before any route exists.

Why there is no recovery

The file is encrypted with the key and nothing else. No escrow, no reset link, no support channel that can decrypt it. That is the property that makes it safe to commit the ciphertext to a repository, and it is the same property that makes a lost key final.

Keep the next one

Put the value in a password manager the day you generate it, not the day you need it. One Shot reads ENV first and falls back to credentials, so a team can also skip the encrypted file entirely and set each secret as an environment variable instead.

Related questions

How do I rotate an API key without taking the app down?

Create the new key at the provider while the old one still works, set it, deploy, verify the app is using it, and only then revoke the old one. Most providers allow several active keys for exactly this reason. Revoking before deploying is what turns a routine rotation into an outage.

Should I use Rails credentials or environment variables for secrets?

Either. The app reads ENV first and falls back to Rails.application.credentials, so a value set in the environment wins and a value in the encrypted file is the default. Use credentials when you want secrets versioned with the code, and environment variables when a platform or a team already manages them elsewhere.

What does SECRET_KEY_BASE actually do in a Rails app?

It is the root secret Rails derives every other key from: the one that signs session cookies, encrypts encrypted cookies, and verifies signed global ids and Active Storage URLs. Change it and every existing session becomes invalid, so every signed-in user is logged out at the moment of deploy.