mongodb/mongoid · error · NotImplementedError

#{self.class} must implement #docs_for_lookup_fallback

Error message

#{self.class} must implement #docs_for_lookup_fallback

What it means

Error "#{self.class} must implement #docs_for_lookup_fallback" thrown in mongodb/mongoid.

Source

Thrown at lib/mongoid/association/eager_loadable.rb:133

      # polymorphic inclusions it leaves out are resolved by the caller.
      #
      # @param [ Mongoid::Criteria ] criteria The criteria to load.
      #
      # @return [ Array<Mongoid::Document> ] The materialized root documents.
      def preload_for_lookup(criteria)
        pipeline = EagerLoad::LookupPipeline.new(criteria).stages
        Eager.run(criteria.inclusions, [], true, pipeline)
      end

      private

      # Returns the materialized documents to use when falling back from
      # $lookup to #includes-style preloading. Must be implemented by each
      # concrete context class.
      #
      # @return [ Array<Mongoid::Document> ] The materialized documents.
      def docs_for_lookup_fallback
        raise NotImplementedError, "#{self.class} must implement #docs_for_lookup_fallback"
      end

      # Returns the inclusions whose target class can't be reached by a $lookup
      # from the root class, which joins only within the same client and database.
      #
      # @return [ Array<Mongoid::Association::Relatable> ] The offending inclusions.
      def inclusions_unreachable_by_lookup
        # Polymorphic associations have no single resolvable klass and are not
        # loaded via $lookup, so they are never offenders.
        criteria.inclusions.reject do |association|
          association.polymorphic? || reachable_by_lookup?(association.klass)
        end
      end

      # Whether a $lookup from a query on the root class can reach the model: it
      # must live in the same client and database.
      def reachable_by_lookup?(model)
        model.client_name == klass.client_name &&

View on GitHub (pinned to 0da0e23d71)

When it happens

Trigger: Thrown at lib/mongoid/association/eager_loadable.rb:133 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mongodb/mongoid@0da0e23d71 (2026-08-23). Data as JSON: /api/errors/5d2a8c7565d5b172. Report an issue: GitHub.