ankane/searchkick · error · ArgumentError

distance must match searchkick options

Error message

distance must match searchkick options

What it means

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

Source

Thrown at lib/searchkick/query.rb:1042

          if ef_search && Searchkick.server_below?("2.16.0")
            raise Error, "ef_search requires OpenSearch 2.16+"
          end

          payload[:query] = {
            knn: {
              field.to_sym => {
                vector: vector,
                k: k,
                filter: filter
              }.merge(ef_search ? {method_parameters: {ef_search: ef_search}} : {})
            }
          }
        end
      else
        if exact
          # prevent incorrect distances/results with Elasticsearch 9.0.0-rc1
          if !Searchkick.server_below?("9.0.0") && field_options[:distance] == "cosine" && distance != "cosine"
            raise ArgumentError, "distance must match searchkick options"
          end

          # https://github.com/elastic/elasticsearch/blob/main/docs/reference/vectors/vector-functions.asciidoc
          source =
            case distance
            when "cosine"
              "(cosineSimilarity(params.query_vector, params.field) + 1.0) * 0.5"
            when "euclidean"
              "double l2 = l2norm(params.query_vector, params.field); 1 / (1 + l2 * l2)"
            when "taxicab"
              "1 / (1 + l1norm(params.query_vector, params.field))"
            when "inner_product"
              "double dot = dotProduct(params.query_vector, params.field); dot > 0 ? dot + 1 : 1 / (1 - dot)"
            else
              raise ArgumentError, "Unknown distance: #{distance}"
            end

          payload[:query] = {

View on GitHub (pinned to 93e901a75b)

When it happens

Trigger: Thrown at lib/searchkick/query.rb:1042 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/bf8dcf85ef20ea1e. Report an issue: GitHub.