ankane/searchkick · error · ArgumentError

distance must match searchkick options for approximate searc

Error message

distance must match searchkick options for approximate search

What it means

Error "distance must match searchkick options for approximate search" thrown in ankane/searchkick.

Source

Thrown at lib/searchkick/query.rb:982

    def set_knn(payload, knn, per_page, offset)
      if term != "*"
        raise ArgumentError, "Use Searchkick.multi_search for hybrid search"
      end

      field = knn[:field]
      field_options = searchkick_options.dig(:knn, field.to_sym) || searchkick_options.dig(:knn, field.to_s) || {}
      vector = knn[:vector]
      distance = knn[:distance] || field_options[:distance]
      exact = knn[:exact]
      exact = field_options[:distance].nil? || distance != field_options[:distance] if exact.nil?
      k = per_page + offset
      ef_search = knn[:ef_search]
      filter = payload.delete(:query)

      if distance.nil?
        raise ArgumentError, "distance required"
      elsif !exact && distance != field_options[:distance]
        raise ArgumentError, "distance must match searchkick options for approximate search"
      end

      if Searchkick.opensearch?
        if exact
          # https://opensearch.org/docs/latest/search-plugins/knn/knn-score-script/#spaces
          space_type =
            case distance
            when "cosine"
              "cosinesimil"
            when "euclidean"
              "l2"
            when "taxicab"
              "l1"
            when "inner_product"
              "innerproduct"
            when "chebyshev"
              "linf"
            else

View on GitHub (pinned to 93e901a75b)

When it happens

Trigger: Thrown at lib/searchkick/query.rb:982 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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