Introduction

Rails encrypted credentials require the RAILS_MASTER_KEY to decrypt config/credentials.yml.enc. Without this key, you cannot read or edit credentials, which blocks application startup in production and prevents developers from managing secrets. This is a common issue during onboarding, deployment, and server migration.

Symptoms

  • ActiveSupport::MessageEncryptor::InvalidMessage: ActiveSupport::MessageEncryptor::InvalidMessage
  • bin/rails credentials:edit opens editor but cannot save (key missing)
  • Application crashes on startup with Missing encryption key to decrypt the credentials file
  • config/master.key file not committed to git (by design)
  • New developer cannot decrypt credentials after cloning the repo

Example error: ``` bin/rails credentials:edit Adding config/master.key to store the encryption key: abc123def456

Save this in a password manager your team can access.

If you lose the key, no one, including you, can access your encrypted credentials.

rails aborted! ActiveSupport::MessageEncryptor::InvalidMessage: ActiveSupport::MessageEncryptor::InvalidMessage ```

Common Causes

  • config/master.key not shared with team members
  • RAILS_MASTER_KEY environment variable not set in production
  • Key rotated but old credentials not re-encrypted
  • .gitignore excludes master.key (correct) but no backup exists
  • Docker container does not receive the master key environment variable

Step-by-Step Fix

  1. 1.Locate the existing master key:
  2. 2.```bash
  3. 3.# Check if master.key exists locally
  4. 4.cat config/master.key

# Check environment variable echo $RAILS_MASTER_KEY

# If using credentials.yml.enc, the key is 32 hex characters ```

  1. 1.Set the master key for the current session:
  2. 2.```bash
  3. 3.# Development
  4. 4.export RAILS_MASTER_KEY=$(cat config/master.key)

# Production (add to your server environment) export RAILS_MASTER_KEY=abc123def456... # Or in systemd service file: # Environment=RAILS_MASTER_KEY=abc123def456... ```

  1. 1.Edit credentials with explicit key:
  2. 2.```bash
  3. 3.# Set editor
  4. 4.export EDITOR="code --wait" # VS Code
  5. 5.export EDITOR="vim" # Vim

# Edit credentials bin/rails credentials:edit

# Or edit a specific environment's credentials bin/rails credentials:edit --environment production ```

  1. 1.Configure for deployment platforms:
  2. 2.```bash
  3. 3.# Heroku
  4. 4.heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)

# Docker docker run -e RAILS_MASTER_KEY=abc123... myapp

# Capistrano (config/deploy/production.rb) set :linked_files, fetch(:linked_files, []).push('config/master.key') # Then place master.key in shared directory on server ```

  1. 1.Rotate a compromised or lost master key:
  2. 2.```bash
  3. 3.# WARNING: This re-encrypts all credentials with a new key
  4. 4.# 1. Decrypt with old key
  5. 5.RAILS_MASTER_KEY=old_key bin/rails credentials:show > /tmp/credentials.yml

# 2. Remove old encrypted file and key rm config/credentials.yml.enc rm config/master.key

# 3. Generate new key and re-encrypt bin/rails credentials:edit # Paste the contents from /tmp/credentials.yml # Rails generates a new master.key automatically

# 4. Deploy new key to all environments rm /tmp/credentials.yml ```

Prevention

  • Store RAILS_MASTER_KEY in a team password manager (1Password, Bitwarden)
  • Add master key to your CI/CD platform's secret variables
  • Use per-environment credentials: credentials/production.yml.enc
  • Document the key retrieval process in your onboarding guide
  • Never commit config/master.key to git
  • Backup the master key in at least two secure locations