paper-trail-gem/paper_trail · warning

PaperTrail %s is not compatible with ActiveRecord %s. We all

Error message

PaperTrail %s is not compatible with ActiveRecord %s. We allow PT
contributors to install incompatible versions of ActiveRecord, and this
warning can be silenced with an environment variable, but this is a bad
idea for normal use. Please install a compatible version of ActiveRecord
instead (%s). Please see the discussion in paper_trail/compatibility.rb
for details.

What it means

PaperTrail deliberately only supports a bounded range of ActiveRecord versions (ACTIVERECORD_GTE '>= 7.1', ACTIVERECORD_LT '< 8.2', set in lib/paper_trail/compatibility.rb:20-21). Since #1213 the gemspec still lets you INSTALL newer/older ActiveRecord so PT contributors can work on compatibility, but at boot check_activerecord compares the loaded AR version against a Gem::Requirement and prints this Kernel.warn when it falls outside the range. It is a warning, not an exception: PT may work, but it is untested and likely to break subtly. The env var PT_SILENCE_AR_COMPAT_WARNING only exists for PT contributors, not production use.

Source

Thrown at lib/paper_trail/compatibility.rb:40

    E_INCOMPATIBLE_AR = <<-EOS
      PaperTrail %s is not compatible with ActiveRecord %s. We allow PT
      contributors to install incompatible versions of ActiveRecord, and this
      warning can be silenced with an environment variable, but this is a bad
      idea for normal use. Please install a compatible version of ActiveRecord
      instead (%s). Please see the discussion in paper_trail/compatibility.rb
      for details.
    EOS

    # Normal users need a warning if they accidentally install an incompatible
    # version of ActiveRecord. Contributors can silence this warning with an
    # environment variable.
    def self.check_activerecord(ar_version)
      raise ::TypeError unless ar_version.instance_of?(::Gem::Version)
      return if ::ENV["PT_SILENCE_AR_COMPAT_WARNING"].present?
      req = ::Gem::Requirement.new([ACTIVERECORD_GTE, ACTIVERECORD_LT])
      unless req.satisfied_by?(ar_version)
        ::Kernel.warn(
          format(
            E_INCOMPATIBLE_AR,
            ::PaperTrail.gem_version,
            ar_version,
            req
          )
        )
      end
    end
  end
end

View on GitHub (pinned to 098058ae47)

Solutions

1. Align ActiveRecord with the supported range stated in the message: in the Gemfile constrain rails/activerecord to a version satisfying >= 7.1 and < 8.2, then run `bundle install`.
2. Or upgrade paper_trail to the newest release that declares support for your ActiveRecord version (check the paper_trail changelog and .github/workflows/test.yml for the tested AR matrix).
3. Contributors only: export PT_SILENCE_AR_COMPAT_WARNING=1 to silence it while working on PT compatibility for the new AR — never set this in production, it hides a real untested-version risk.

Example fix

# Gemfile - before
gem "rails", "~> 8.2"
gem "paper_trail"

# Gemfile - after (satisfies >= 7.1, < 8.2)
gem "rails", "~> 8.1"
gem "paper_trail"
# then: bundle update rails activerecord

# Check before relying on PaperTrail, e.g. in config/initializers/paper_trail_compat.rb
req = Gem::Requirement.new([
  PaperTrail::Compatibility::ACTIVERECORD_GTE,
  PaperTrail::Compatibility::ACTIVERECORD_LT
])
ar_version = Gem.loaded_specs.fetch("activerecord").version
fail "ActiveRecord #{ar_version} outside PaperTrail-supported range #{req}" unless req.satisfied_by?(ar_version)

When it happens

Trigger: Booting any Rails app (or running `PaperTrail::Compatibility.check_activerecord(Gem.loaded_specs["activerecord"].version)`) with activerecord >= 8.2 or < 7.1 installed next to this paper_trail release. Typically happens right after `bundle update rails` or adding `gem "rails", "~> 8.2"` while paper_trail is still pinned to a release whose gemspec range stops at 8.1.

Common situations: Upgrading Rails to a brand-new minor before a compatible paper_trail release ships; a loose Gemfile (`gem "activerecord"` with no constraint) letting bundler resolve an AR newer than PT supports; CI suddenly showing the warning after a lockfile refresh even though the app code did not change.

Related errors

• Passing Version class name as `has_paper_trail class_name: %
• Passing versions association name as `has_paper_trail versio
• Attribute #{k} does not exist on #{version.item_type} (Versi

AI-assisted analysis of paper-trail-gem/paper_trail@098058ae47 (2026-08-21). Data as JSON: /api/errors/93b00addb4b4be17. Report an issue: GitHub.