thoughtbot/shoulda-matchers · error · ExistingRecordInvalid

validate_uniqueness_of works by matching a new record agains

Error message

validate_uniqueness_of works by matching a new record against an
existing record. If there is no existing record, it will create one
using the record you provide.

While doing this, the following error was raised:

#{Shoulda::Matchers::Util.indent(underlying_exception.message, 2)}

The best way to fix this is to provide the matcher with a record where
any required attributes are filled in with valid values beforehand.

What it means

Error "validate_uniqueness_of works by matching a new record against an existing record. If there is no existing record, it will create one using the record you provide. While doing this, the following error was raised: #{Shoulda::Matchers::Util.indent(underlying_exception.message, 2)} The best way to fix this is to provide the matcher with a record where any required attributes are filled in with valid values beforehand." thrown in thoughtbot/shoulda-matchers.

Source

Thrown at lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb:599

        def find_or_create_existing_record
          @existing_record = find_existing_record

          unless @existing_record
            @existing_record = create_existing_record
            @existing_record_created = true
          end
        end

        def find_existing_record
          model.first.presence
        end

        def create_existing_record
          @given_record.tap do |existing_record|
            existing_record.save(validate: false)
          end
        rescue ::ActiveRecord::StatementInvalid => e
          raise ExistingRecordInvalid.create(underlying_exception: e)
        end

        def update_existing_record!(value)
          if existing_value_read != value
            set_attribute_on_existing_record!(@attribute, value)
            # It would be nice if we could ensure that the record was valid,
            # but that would break users' existing tests
            existing_record.save(validate: false)
          end

          true
        end

        def arbitrary_non_blank_value
          non_blank_value = dummy_value_for(@attribute)
          limit = column_limit_for(@attribute)

          is_string_value = non_blank_value.is_a?(String)

View on GitHub (pinned to 79cdfbc326)

When it happens

Trigger: Thrown at lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb:599 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of thoughtbot/shoulda-matchers@79cdfbc326 (2026-08-23). Data as JSON: /api/errors/9b16d7ce1f334c76. Report an issue: GitHub.