I recently solved a particularly troublesome issue where our QA environment (configured just like production) was unable to load a class that we kept in our lib/ directory in our Rails application.

In application.rb I have this:

# ./config/application.rb  
config.autoload_paths += %W(#{config.root}/lib)

And you might think that ought to be enough. Classes defined under lib, if they meet Rails' opinions on naming, should be autoloaded. And in a development environment your assumption will [generally] be correct. But its when config.threadsafe! or jruby_max_runtimes is set to 1 - which implies thread safety - that this assumption falls flat. Classes and modules under lib/ - or under any autoload path for that matter - will need to be explicitly loaded through a require statement or with the following approach:

# ./config/application.rb  
# when threadsafe is enabled (i.e. JRuby max runtimes 1 does this) then classes/modules
# in lib needs to loaded through some mechanism other than autoload_paths
config.autoload_paths.each do |path|  
  config.eager_load_paths << path
end  

That line there appears right after my config.autoloadpaths line in application.rb. I tried placing it explicitly in my config/qa.rb but it turns out that at some point the eagerload_paths array becomes frozen and you can't add anything else to it. So perhaps I have some other unintended consequences to worry about but at least right now my QA system works.