Gotchas

Security

Spreadsheet applications vulnerable to unescaped CSV data

If your CSV export includes untrusted data provided by your users, it's possible that they could include an executable formula that could call arbitrary commands on your computer. See #4256 for more details.

Session Commits & Asset Pipeline

When configuring the asset pipeline ensure that the asset prefix (config.assets.prefix) is not the same as the namespace of ActiveAdmin (default namespace is /admin). If they are the same Sprockets will prevent the session from being committed. Flash messages won't work and you will be unable to use the session for storing anything.

For more information see the following post.

Helpers

There are two known gotchas with helpers. This hopefully will help you to find a solution.

Helpers are not reloading in development

This is a known and still open issue the only way is to restart your server each time you change a helper.

Helper maybe not included by default

If you use config.action_controller.include_all_helpers = false in your application config, you need to include it by hand.

Solutions

First use an override

This works for all ActiveAdmin resources at once. Please follow the Rails guidelines for overriding this safely alongside Zeitwerk.

ActiveAdmin::BaseController.class_eval do
  helper ApplicationHelper
end

Second use the controller method

This works only for one resource at a time.

ActiveAdmin.register User do
  controller do
    helper UserHelper
  end
end

CSS

To avoid overriding your application styles with the ActiveAdmin styles, remove the require_tree command from your application's CSS files, where the active_admin.scss is in the tree.

Deprecation warnings with modern sass build tools

Active Admin v3's SCSS is written for sassc, which follows an older version of the SCSS specification. If you use a Node-based build system like esbuild, webpacker, or vite, you may encounter deprecation warnings for color functions like this when compiling assets:

DEPRECATION WARNING: lighten() is deprecated

As a quick workaround, you may be able to silence these warnings by passing the quietDeps scss compilation option in your build system. With vite, follow these instructions: https://github.com/vitejs/vite/discussions/4013#discussioncomment-10793687 (note this requires installing the sass-embedded dependency).

Conflicts

With gems that provides a search class method on a model

If a gem defines a search class method on a model, this can result in conflicts with the same method provided by ransack (a dependency of ActiveAdmin).

Each of this conflicts need to solved is a different way. Some solutions are listed below.

tire, retire and elasticsearch-rails

This conflict can be solved, by using explicitly the search method of tire, retire or elasticsearch-rails:

For tire and retire

YourModel.tire.search

For elasticsearch-rails

YourModel.__elasticsearch__.search

Sunspot Solr

YourModel.solr_search

Authentication & Application Controller

The ActiveAdmin::BaseController inherits from the ApplicationController. Any authentication method(s) specified in the ApplicationController callbacks will be called instead of the authentication method in the active admin config file. For example, if the ApplicationController has a callback before_action :custom_authentication_method and the config file's authentication method is config.authentication_method = :authenticate_active_admin_user, then custom_authentication_method will be called instead of authenticate_active_admin_user.