mongodb/mongoid · error · Mongoid::Errors::DocumentNotFound

Document(s) not found for class

Error message

Document(s) not found for class %{klass} with id(s) %{missing}.

What it means

While processing nested attributes, update_nested_relation could not find the referenced document inside the embedded association (the _id is absent among existing children). Embedded documents cannot be fetched from the database independently, so DocumentNotFound is raised.

Solutions

1. Verify the child ids submitted match documents actually embedded in the parent
2. Build new children without an id instead of updating a nonexistent one

When it happens

Trigger: Thrown at lib/mongoid/association/nested/many.rb:193 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/e90461ff7fe7f254. Report an issue: GitHub.

Appendix: source

Thrown at lib/mongoid/association/nested/many.rb:193

        #   builder.update_nested_relation(parent, id, attrs)
        #
        # @param [ Document ] parent The parent document.
        # @param [ String | BSON::ObjectId ] id of the related document.
        # @param [ Hash ] attrs The single document attributes to process.
        def update_nested_relation(parent, id, attrs)
          first = existing.first
          converted = first ? convert_id(first.class, id) : id

          if existing.where(_id: converted).exists?
            # document exists in association
            doc = existing.find(converted)
            if destroyable?(attrs)
              destroy(parent, existing, doc)
            else
              update_document(doc, attrs)
            end
          elsif association.embedded?
            raise Errors::DocumentNotFound.new(association.klass, id)
          elsif association.is_a?(Association::Referenced::HasAndBelongsToMany) || Mongoid.allow_reparenting_via_nested_attributes?
            unless destroyable?(attrs)
              Mongoid::Warnings.warn_reparenting_via_nested_attributes if Mongoid.allow_reparenting_via_nested_attributes?

              # push existing document to association
              doc = association.klass.unscoped.find(converted)
              # find returns nil instead of raising when
              # Mongoid.raise_not_found_error is false; a missing document
              # must still be an error here, consistent with the other
              # not-found branches.
              raise Errors::DocumentNotFound.new(association.klass, id) if doc.nil?

              update_document(doc, attrs)
              existing.push(doc)
            end
          else
            raise Errors::DocumentNotFound.new(association.klass, { _id: id, association.foreign_key => parent.id })
          end

View on GitHub (pinned to 0da0e23d71)