Fix Error: Error connecting Stimulus controller: 'search' controller is not registered in Rails

This error occurs when Stimulus cannot find a registered controller matching the data-controller attribute in your HTML. The controller file may be missing, not imported in the controllers index, or named incorrectly. Ensure the file naming convention matches and the controller is properly registered with the Stimulus application instance.

Reading the Stack Trace

Here's what each line means:

• at Application.connectController (stimulus.min.js:1:8234): Stimulus tries to connect a controller to the DOM element but cannot find the registered controller class.
• at Router.scopeConnected (stimulus.min.js:1:4321): The router detected a data-controller attribute and tried to connect the matching controller.
• at app/javascript/controllers/application.js:8:1: The Stimulus application initialization where controllers should be registered.

Common Causes

<!-- HTML references 'search' controller -->
<div data-controller="search">
  <input data-search-target="input" type="text">
</div>
<!-- But app/javascript/controllers/search_controller.js does not exist -->

// app/javascript/controllers/index.js
import { application } from './application'
// search_controller is not imported here

// File: app/javascript/controllers/searchController.js  (wrong)
// Should be: app/javascript/controllers/search_controller.js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  connect() { console.log('connected') }
}

The Fix

Create the controller file following Stimulus naming conventions: the file must be named search_controller.js for a data-controller='search' attribute. If using importmap, ensure pin_all_from covers the controllers directory.

<!-- Controller referenced but file missing or not registered -->
<div data-controller="search">
  <input data-search-target="input" type="text">
</div>

// app/javascript/controllers/search_controller.js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static targets = ['input', 'results']

  connect() {
    console.log('Search controller connected')
  }

  search() {
    const query = this.inputTarget.value
    // Perform search logic
  }
}

Testing the Fix

require 'rails_helper'

RSpec.describe 'Search Stimulus controller', type: :system do
  it 'connects the search controller' do
    visit search_path
    expect(page).to have_css('[data-controller="search"]')
  end

  it 'has the search input target' do
    visit search_path
    expect(page).to have_css('[data-search-target="input"]')
  end
end

RSpec.describe 'JavaScript modules', type: :request do
  it 'loads without errors' do
    get root_path
    expect(response.body).not_to include('controller is not registered')
  end
end

Run your tests:

bundle exec rspec spec/system/search_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-stimulus-controller,git add app/javascript/controllers/search_controller.js,git commit -m "fix: create search stimulus controller with proper naming",git push origin fix/rails-stimulus-controller

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. Create the missing Stimulus controller file with correct naming.
2. Ensure pin_all_from or explicit imports register the controller.
3. Run system specs to verify the controller connects.
4. Open a pull request.
5. Merge and verify Stimulus interactions work in staging.

Frequently Asked Questions