ankane/searchkick · error · ArgumentError

Invalid value for callbacks

Error message

Invalid value for callbacks

What it means

The `callbacks` option controls how searchkick syncs records to the index on save/destroy. It accepts exactly `:inline` (default), `true` (alias of inline), `false` (disable), `:async` (background job), and `:queue` (ActiveJob queue for high-throughput bulk). Anything else — a string, `"async"`, `nil`-like values, or a typo — raises `ArgumentError` at class-load time.

Source

Thrown at lib/searchkick/model.rb:30

      end

      unknown_keywords = options.keys - [:_all, :_type, :batch_size, :callbacks, :callback_options, :case_sensitive, :conversions, :conversions_v2, :deep_paging, :default_fields,
        :filterable, :geo_shape, :highlight, :ignore_above, :index_name, :index_prefix, :inheritance, :job_options, :knn, :language,
        :locations, :mappings, :match, :max_result_window, :merge_mappings, :routing, :searchable, :search_synonyms, :settings, :similarity,
        :special_characters, :stem, :stemmer, :stem_conversions, :stem_exclusion, :stemmer_override, :suggest, :synonyms, :text_end,
        :text_middle, :text_start, :unscope, :word, :word_end, :word_middle, :word_start]
      raise ArgumentError, "unknown keywords: #{unknown_keywords.join(", ")}" if unknown_keywords.any?

      raise "Only call searchkick once per model" if respond_to?(:searchkick_index)

      Searchkick.models << self

      options[:_type] ||= -> { searchkick_index.klass_document_type(self, true) }
      options[:class_name] = model_name.name

      callbacks = options.key?(:callbacks) ? options[:callbacks] : :inline
      unless [:inline, true, false, :async, :queue].include?(callbacks)
        raise ArgumentError, "Invalid value for callbacks"
      end
      callback_options = (options[:callback_options] || {}).dup
      callback_options[:if] = [-> { Searchkick.callbacks?(default: callbacks) }, callback_options[:if]].compact.flatten(1)

      base = self

      mod = Module.new
      include(mod)
      mod.module_eval do
        def reindex(method_name = nil, mode: nil, refresh: false, ignore_missing: nil, job_options: nil)
          self.class.searchkick_index.reindex([self], method_name: method_name, mode: mode, refresh: refresh, ignore_missing: ignore_missing, job_options: job_options, single: true)
        end unless base.method_defined?(:reindex)

        def similar(**options)
          self.class.searchkick_index.similar_record(self, **options)
        end unless base.method_defined?(:similar)

        def search_data

View on GitHub (pinned to 93e901a75b)

Solutions

1. Use one of the five valid values: `:inline`, `true`, `false`, `:async`, `:queue`.
2. When the value comes from config, normalize it: `callbacks: ENV.fetch("SEARCHKICK_CALLBACKS", "inline").then { |v| %w[true false].include?(v) ? v == "true" : v.to_sym }`.
3. For `:async`/`:queue`, ensure ActiveJob/Sidekiq is configured (a queue adapter and workers running), since the error often appears while wiring those up.
4. Check the gem version's README — supported callbacks values have changed across majors.

Example fix

# before
searchkick callbacks: ENV["SEARCHKICK_CALLBACKS"] # "async" (String) => ArgumentError

# after
raw = ENV.fetch("SEARCHKICK_CALLBACKS", "inline")
callbacks = %w[true false].include?(raw) ? raw == "true" : raw.to_sym
searchkick callbacks: callbacks

VALID_CALLBACKS = [:inline, true, false, :async, :queue]
raw = ENV.fetch("SEARCHKICK_CALLBACKS", "inline")
callbacks = %w[true false].include?(raw) ? raw == "true" : raw.to_sym
raise ArgumentError, "callbacks must be one of #{VALID_CALLBACKS.inspect}" unless VALID_CALLBACKS.include?(callbacks)
class Product < ApplicationRecord
  searchkick callbacks: callbacks
end

def valid_callbacks_value?(v)
  [:inline, true, false, :async, :queue].include?(v)
end

When it happens

Trigger: `searchkick callbacks: "async"` (string instead of symbol), `callbacks: :background`, `callbacks: :sidekiq`, or `callbacks: nil`/`:default` on a model, triggering the check when the class loads.

Common situations: Reading older searchkick docs/tutorials where `"false"` or other values were shown; setting callbacks from an ENV var or YAML without casting (`callbacks: ENV["SEARCHKICK_CALLBACKS"]` yields a string or nil); renaming from `:async` to `:queue` and typo'ing; wrapping in quotes by copy-paste.

Related errors

• Unknown stemmer: #{stemmer[:type]}
• unknown keywords: #{unknown_keywords.join(", ")}
• Multiple clients found - set Searchkick.client_type = :elast
• No client found - install the `elasticsearch` or `opensearch
• The `elasticsearch` gem must be 8+

AI-assisted analysis of ankane/searchkick@93e901a75b (2026-08-21). Data as JSON: /api/errors/793917a4a1e35940. Report an issue: GitHub.