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

Invalid association option

Error message

Invalid association option :%{option} for association '%{name}' on class %{klass}.

What it means

Relatable#validate! is the association-macro option validator: each option key is checked against the association class's VALID_OPTIONS list, and any unknown option is rejected when the association is defined. A typo'd or unsupported option is the usual cause.

Solutions

1. Remove the misspelled option or correct it to a valid one
2. Check the association type's VALID_OPTIONS for supported options

When it happens

Trigger: Thrown at lib/mongoid/association/relatable.rb:421 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/d88d4573a982f88c. Report an issue: GitHub.

Appendix: source

Thrown at lib/mongoid/association/relatable.rb:421

        Association::Accessors.define_ids_setter!(self)
      end

      def define_counter_cache_callbacks!
        return unless counter_cached?

        Association::Referenced::CounterCache.define_callbacks!(self)
      end

      def define_dependency!
        return unless dependent

        Association::Depending.define_dependency!(self)
      end

      def validate!
        @options.keys.each do |opt|
          unless self.class::VALID_OPTIONS.include?(opt)
            raise Errors::InvalidRelationOption.new(@owner_class, name, opt, self.class::VALID_OPTIONS)
          end
        end

        if @options.key?(:fallback)
          unless @options[:fallback].respond_to?(:call)
            raise ArgumentError,
                  "The :fallback option for association '#{name}' on " \
                  "#{@owner_class} must be a Proc or lambda."
          end

          if @options.key?(:autobuild)
            raise ArgumentError,
                  "The :fallback option for association '#{name}' on " \
                  "#{@owner_class} cannot be combined with :autobuild."
          end
        end

        [ name, :"#{name}?", :"#{name}=" ].each do |n|

View on GitHub (pinned to 0da0e23d71)