Fix ActiveRecord::PendingMigrationError: Migrations are pending. To resolve this issue, run: bin/rails db:migrate RAILS_ENV=development in Rails

This error means your database schema is out of sync with your migration files. Rails detected migrations that have not been applied yet. Run bin/rails db:migrate to apply pending migrations and update your schema. This commonly happens after pulling new code that includes database changes from teammates.

Reading the Stack Trace

Here's what each line means:

• activerecord (7.1.3) lib/active_record/migration.rb:621:in `check_pending!': Rails checks for pending migrations on every request in development mode and raises this error if any are found.
• actionpack (7.1.3) lib/action_dispatch/middleware/callbacks.rb:27:in `block in call': The migration check runs as middleware before your request reaches the controller.
• actionpack (7.1.3) lib/action_dispatch/middleware/executor.rb:14:in `call': The executor middleware wraps the request lifecycle where the pending check is triggered.

Common Causes

# db/migrate/20240101120000_add_status_to_orders.rb exists but has not been run
class AddStatusToOrders < ActiveRecord::Migration[7.1]
  def change
    add_column :orders, :status, :string, default: 'pending'
  end
end

# Terminal output:
# $ rails generate migration AddEmailToProfiles email:string
# create db/migrate/20240315090000_add_email_to_profiles.rb
# Developer starts server without running db:migrate

# Migrations applied to development but test DB is behind
# $ RAILS_ENV=test rails runner 'puts ActiveRecord::Base.connection.migration_context.needs_migration?'
# => true

The Fix

Run bin/rails db:migrate to apply all pending migrations. Also run it for the test environment if needed. Use db:migrate:status to verify all migrations are applied.

# Pending migration exists but has not been applied
# db/migrate/20240101120000_add_status_to_orders.rb
class AddStatusToOrders < ActiveRecord::Migration[7.1]
  def change
    add_column :orders, :status, :string, default: 'pending'
  end
end
# Server started without running migrations

# Run pending migrations:
# $ bin/rails db:migrate
# $ bin/rails db:migrate RAILS_ENV=test

# Verify migration status:
# $ bin/rails db:migrate:status
#  Status   Migration ID    Migration Name
#  up       20240101120000  Add status to orders

Testing the Fix

require 'rails_helper'

RSpec.describe Order, type: :model do
  describe 'status column' do
    it 'has a default status of pending' do
      order = Order.create!(total: 100)
      expect(order.status).to eq('pending')
    end

    it 'allows updating status' do
      order = Order.create!(total: 100)
      order.update!(status: 'shipped')
      expect(order.reload.status).to eq('shipped')
    end
  end
end

Run your tests:

bundle exec rspec spec/models/order_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-migration-pending,bin/rails db:migrate,git add db/migrate/ db/schema.rb,git commit -m "fix: apply pending migration for orders status column",git push origin fix/rails-migration-pending

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports: ['5432:5432']
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: bin/rails db:setup
      - run: bundle exec rspec

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

gem install bugstack

require 'bugstack'

Bugstack.init(api_key: ENV['BUGSTACK_API_KEY'])

Deploying the Fix (Manual Path)

1. Run bin/rails db:migrate locally and verify the schema change.
2. Run the full test suite to confirm nothing is broken.
3. Open a pull request with the updated schema.rb.
4. Wait for CI to pass and get a code review.
5. Merge to main and run db:migrate on staging before promoting to production.

Frequently Asked Questions