Fix ThreadError: deadlock; recursive locking (ThreadError) in Rails

This error occurs when a thread tries to acquire a lock it already holds, creating a deadlock. In Rails, this often happens with class-level mutable state accessed from multiple threads in a Puma multi-threaded server. Use Mutex correctly, avoid recursive locking, and prefer thread-local variables or Concurrent::Map for shared state.

Reading the Stack Trace

Here's what each line means:

• app/services/rate_limiter.rb:18:in `synchronize': The Mutex.synchronize call deadlocks because the mutex is already locked by the current thread.
• app/services/rate_limiter.rb:22:in `check': The check method is called recursively within the synchronized block, causing recursive locking.
• app/controllers/api_controller.rb:6:in `check_rate_limit': The before_action calls the rate limiter which triggers the deadlock.

Common Causes

class RateLimiter
  MUTEX = Mutex.new
  @@counts = {}

  def self.throttle(key)
    MUTEX.synchronize do
      check(key)  # check also tries to synchronize on MUTEX
    end
  end

  def self.check(key)
    MUTEX.synchronize do
      @@counts[key] ||= 0
      @@counts[key] += 1
    end
  end
end

class Counter
  @@total = 0

  def self.increment
    @@total += 1  # Not thread-safe
  end
end

SETTINGS = {}

class SettingsLoader
  def self.get(key)
    SETTINGS[key] ||= load_from_db(key)  # Race condition
  end
end

The Fix

Replace the Mutex and class variable with Concurrent::Map from the concurrent-ruby gem. Concurrent::Map provides thread-safe operations without explicit locking, eliminating the deadlock risk while remaining performant.

class RateLimiter
  MUTEX = Mutex.new
  @@counts = {}

  def self.throttle(key)
    MUTEX.synchronize do
      check(key)
    end
  end

  def self.check(key)
    MUTEX.synchronize do
      @@counts[key] ||= 0
      @@counts[key] += 1
    end
  end
end

require 'concurrent'

class RateLimiter
  COUNTS = Concurrent::Map.new

  def self.throttle(key)
    count = COUNTS.compute(key) do |val|
      (val || 0) + 1
    end
    count <= rate_limit_threshold
  end

  def self.rate_limit_threshold
    100
  end
end

Testing the Fix

require 'rails_helper'
require 'concurrent'

RSpec.describe RateLimiter do
  before { RateLimiter::COUNTS.clear }

  it 'increments count for a key' do
    5.times { RateLimiter.throttle('user:1') }
    expect(RateLimiter::COUNTS['user:1']).to eq(5)
  end

  it 'is thread-safe' do
    threads = 10.times.map do
      Thread.new { 100.times { RateLimiter.throttle('user:2') } }
    end
    threads.each(&:join)
    expect(RateLimiter::COUNTS['user:2']).to eq(1000)
  end
end

Run your tests:

bundle exec rspec spec/services/rate_limiter_spec.rb

Pushing Through CI/CD

git checkout -b fix/rails-thread-safety,git add app/services/rate_limiter.rb Gemfile,git commit -m "fix: use Concurrent::Map for thread-safe rate limiting",git push origin fix/rails-thread-safety

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. Replace Mutex-based code with Concurrent::Map.
2. Add thread-safety specs with multi-threaded assertions.
3. Run specs under multi-threaded conditions.
4. Open a pull request.
5. Merge and monitor for thread-related errors in production.

Frequently Asked Questions