The #{option_name} configuration option is deprecated, pleas

Error message

The #{option_name} configuration option is deprecated, please use #{replacement_option_name}.

What it means

register_deprecated_instance_option (lib/rails_admin/config/configurable.rb:85) is RailsAdmin's machinery for retired per-field/per-section options. When a deprecated option registered WITH a replacement name is called, it emits exactly this ActiveSupport::Deprecation warning ('The X configuration option is deprecated, please use Y.') and then forwards arguments/block to the replacement. Live pairs in this codebase: field-level eager_load? → eager_load (lib/rails_admin/config/fields/base.rb:274) and multiple_file_upload field's delete_key → delete_value (lib/rails_admin/config/fields/types/multiple_file_upload.rb:32).

Source

Thrown at lib/rails_admin/config/configurable.rb:88

              instance_variable_set("@#{option_name}_registered", args[0].nil? ? block : args[0])
            else
              # Invocation without args nor block --> It's the use of the option, i.e. getter
              value = instance_variable_get("@#{option_name}_registered")
              case value
              when Proc
                value = with_recurring(option_name, value, default)
              when nil
                value = instance_eval(&default)
              end
              value
            end
          end
        end

        def register_deprecated_instance_option(option_name, replacement_option_name = nil, scope = self)
          scope.send(:define_method, option_name) do |*args, &block|
            if replacement_option_name
              ActiveSupport::Deprecation.warn("The #{option_name} configuration option is deprecated, please use #{replacement_option_name}.")
              send(replacement_option_name, *args, &block)
            elsif block_given?
              yield
            else
              raise "The #{option_name} configuration option is removed without replacement."
            end
          end
        end

        # Register a class option. Class option is a configuration
        # option that stores it's value within a class object's instance variable
        # and is accessed by a class method. Both go by the name of the option.
        def register_class_option(option_name, &default)
          scope = class << self; self; end
          register_instance_option(option_name, scope, &default)
        end
      end
    end

View on GitHub (pinned to 0690a5e62f)

Solutions

Rename the option to the replacement named in the warning message — e.g. delete_key → delete_value, eager_load? → eager_load — keeping the same arguments/block; the old call already forwards to it, so behavior is identical.
Search the whole app for the old option name (grep -r 'delete_key\|eager_load?' config/initializers app) since each occurrence warns independently when its model config loads.
If the option was registered without replacement (message would say 'removed without replacement'), delete the call entirely — for the block-registered ones (momentjs_format, sidescroll, sort_reverse) see their dedicated entries.

Example fix

# before
RailsAdmin.config do |config|
  config.model Article do
    field :attachments, :multiple_file_upload do
      delete_key 'article[attachments_ids]' # warns: deprecated, use delete_value
    end
  end
end

# after
RailsAdmin.config do |config|
  config.model Article do
    field :attachments, :multiple_file_upload do
      delete_value 'article[attachments_ids]'
    end
  end
end

Defensive patterns

Strategy: validation

Validate before calling

# Guard a config helper that refuses deprecated option names
DEPRECATED = { delete_key: :delete_value, 'eager_load?'.to_sym => :eager_load }.freeze
def configure_field(field, option, *args, &block)
  if (replacement = DEPRECATED[option])
    Rails.logger.info("migrating #{option} -> #{replacement}")
    field.send(replacement, *args, &block)
  else
    field.send(option, *args, &block)
  end
end

Type guard

deprecated_option? = ->(name) { name.to_s.end_with?('?') || %i[delete_key momentjs_format sidescroll sort_reverse].include?(name) }

Prevention

When a deprecation warning names a replacement, rename the call in the same commit — the message itself tells you the new API.
Centralize per-model rails_admin config in reviewed files rather than scattering DSL calls, so renames are one grep away.
Run the admin suite with deprecations raised (ActiveSupport::Deprecation.behavior = :raise) to catch these on the first model page load.

When it happens

Trigger: Using a replaced option in a model config block, e.g. `field :attachments, :multiple_file_upload do delete_key 'ids' end` or `field :team do eager_load? true end`. The warning fires when the config block is evaluated (at first load of that model's config, typically the first admin request touching the model). Note the sibling case: options registered without a replacement and without a custom block raise 'The X configuration option is removed without replacement.' instead of warning.

Common situations: Initializer or per-model config carried over from an older rails_admin where the old option name was correct; renaming churn during 2.x→3.x upgrades (eager_load? → eager_load, delete_key → delete_value); CI with deprecations-as-errors failing on the first admin page spec.

Related errors

AI-assisted analysis of railsadminteam/rails_admin@0690a5e62f (2026-08-21). Data as JSON: /api/errors/0c4da1b8eaa38bc9. Report an issue: GitHub.