Fix Importmap::Engine::Error: Could not find javascript module 'controllers/hello_controller' in importmap in Rails

This error occurs when importmap-rails cannot resolve a JavaScript module referenced in your code. The module is not pinned in config/importmap.rb or the file path does not match the pin name. Add the missing pin to your importmap configuration or verify the file exists at the expected path under app/javascript.

Reading the Stack Trace

Here's what each line means:

• importmap-rails (2.0.1) lib/importmap/map.rb:55:in `resolve': The importmap resolver cannot find the module in its pin registry.
• importmap-rails (2.0.1) lib/importmap/map.rb:32:in `to_json': Importmap is generating the JSON module map for the browser when it encounters the missing module.
• app/views/layouts/application.html.erb:12:in `_app_views_layouts_application_html_erb__render': The layout template includes the importmap tag which triggers the resolution.

Common Causes

# config/importmap.rb
pin 'application', preload: true
# Missing: pin_all_from 'app/javascript/controllers', under: 'controllers'

# config/importmap.rb
pin 'controllers/hello_controller'
# But file is at app/javascript/controllers/hello-controller.js (hyphen vs underscore)

// app/javascript/application.js
import 'lodash'  // Not pinned in importmap.rb

The Fix

Use pin_all_from to automatically pin all JavaScript files in the controllers directory. This maps every file in app/javascript/controllers to a module name under the controllers namespace, so Stimulus controllers are automatically discoverable.

# config/importmap.rb
pin 'application', preload: true
# No controller pins defined

# config/importmap.rb
pin 'application', preload: true
pin '@hotwired/turbo-rails', to: 'turbo.min.js', preload: true
pin '@hotwired/stimulus', to: 'stimulus.min.js', preload: true
pin_all_from 'app/javascript/controllers', under: 'controllers'

Testing the Fix

require 'rails_helper'

RSpec.describe 'Importmap configuration', type: :request do
  it 'renders the layout without importmap errors' do
    get root_path
    expect(response).to have_http_status(:ok)
  end

  it 'includes importmap script tag' do
    get root_path
    expect(response.body).to include('importmap')
  end

  it 'resolves all pinned modules' do
    importmap = Rails.application.importmap
    expect { importmap.to_json(resolver: ActionController::Base.helpers) }.not_to raise_error
  end
end

Run your tests:

bundle exec rspec spec/requests/importmap_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-importmap-module,git add config/importmap.rb,git commit -m "fix: pin all stimulus controllers in importmap configuration",git push origin fix/rails-importmap-module

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. Update config/importmap.rb with the correct pins.
2. Verify all JavaScript modules resolve with bin/importmap audit.
3. Run the test suite.
4. Open a pull request.
5. Merge and verify JavaScript loads correctly in staging.

Frequently Asked Questions