Fix ActiveStorage::FileNotFoundError: ActiveStorage::FileNotFoundError in Rails

This error occurs when ActiveStorage cannot find the blob file in the configured storage service. The file may have been deleted from the storage backend, the storage configuration may be wrong, or the blob record exists in the database but the actual file is missing. Verify your storage.yml configuration and check file existence.

Reading the Stack Trace

Here's what each line means:

• activestorage (7.1.3) lib/active_storage/service/disk_service.rb:142:in `stream': The disk service cannot locate the file at the expected path in the storage directory.
• activestorage (7.1.3) lib/active_storage/blobs/proxy_controller.rb:17:in `show': The blob proxy controller is trying to serve the file to the client.
• activestorage (7.1.3) lib/active_storage/service/disk_service.rb:25:in `download': The download method fails because the underlying file does not exist on disk.

Common Causes

# The blob record exists:
# ActiveStorage::Blob.find_by(key: 'abc123') => #<Blob key: 'abc123'>
# But the file is missing:
# storage/ab/c1/abc123 => File not found

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join('storage') %>
# But files were uploaded to tmp/storage previously

# config/environments/production.rb
# config.active_storage.service = :amazon  # This line is missing

The Fix

Ensure the storage.yml configuration points to the correct storage root directory and configure a durable cloud storage service like S3 for production to prevent file loss.

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join('tmp/storage') %>

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join('storage') %>

amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: us-east-1
  bucket: myapp-production

Testing the Fix

require 'rails_helper'

RSpec.describe 'ActiveStorage attachments', type: :model do
  describe User do
    it 'attaches an avatar' do
      user = create(:user)
      user.avatar.attach(
        io: File.open(Rails.root.join('spec/fixtures/files/avatar.png')),
        filename: 'avatar.png',
        content_type: 'image/png'
      )
      expect(user.avatar).to be_attached
    end

    it 'downloads the attached file' do
      user = create(:user, :with_avatar)
      expect(user.avatar.download).to be_present
    end
  end
end

Run your tests:

bundle exec rspec spec/models/user_active_storage_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-active-storage-config,git add config/storage.yml config/environments/production.rb,git commit -m "fix: correct ActiveStorage service configuration",git push origin fix/rails-active-storage-config

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. Verify storage.yml has the correct configuration.
2. Set the active_storage.service in each environment config.
3. Run ActiveStorage specs.
4. Open a pull request.
5. Merge and verify file uploads and downloads work in staging.

Frequently Asked Questions