rubocop/rubocop · error · RuboCop::IncorrectCopNameError

Unrecognized cop or department: %<name>s.

Error message

Unrecognized cop or department: %<name>s.

What it means

RuboCop validates every name passed via --only or --except against Cop::Registry.global (cop names, department names, plus the special Syntax departments "Syntax" and "Lint/Syntax"). If a name matches none of these, it raises IncorrectCopNameError, and the message appends a "Did you mean?" suggestion computed by NameSimilarity.find_similar_names over all registered cop names.

Source

Thrown at lib/rubocop/options.rb:359

  class OptionsValidator
    class << self
      SYNTAX_DEPARTMENTS = %w[Syntax Lint/Syntax].freeze
      private_constant :SYNTAX_DEPARTMENTS

      # Cop name validation must be done later than option parsing, so it's not
      # called from within Options.
      def validate_cop_list(names)
        return unless names

        cop_names = Cop::Registry.global.names
        departments = Cop::Registry.global.departments.map(&:to_s)

        names.each do |name|
          next if cop_names.include?(name)
          next if departments.include?(name)
          next if SYNTAX_DEPARTMENTS.include?(name)

          raise IncorrectCopNameError, format_message_from(name, cop_names)
        end
      end

      private

      def format_message_from(name, cop_names)
        message = 'Unrecognized cop or department: %<name>s.'
        message_with_candidate = "%<message>s\nDid you mean? %<candidate>s"
        corrections = NameSimilarity.find_similar_names(name, cop_names)

        if corrections.empty?
          format(message, name: name)
        else
          format(message_with_candidate, message: format(message, name: name),
                                         candidate: corrections.join(', '))
        end
      end
    end

View on GitHub (pinned to ea712edf2b)

Solutions

1. Read the "Did you mean?" line printed with the error and re-run with the suggested exact cop name.
2. Verify the exact spelling with `rubocop --show-cops` (or `rubocop --list-cops`) and copy the name from there.
3. If this appeared after a RuboCop upgrade, check the changelog for renamed/removed cops and update the list.
4. For custom/third-party cops, make sure the gem is required (plugins: or require: in .rubocop.yml) so the cop is registered before validation.

Example fix

# before
rubocop --only Style/StringLterals
# after
rubocop --only Style/StringLiterals

require 'rubocop'

valid = RuboCop::Cop::Registry.global.names
valid_depts = RuboCop::Cop::Registry.global.departments.map(&:to_s) + %w[Syntax Lint/Syntax]

cop_list = %w[Style/StringLiterals Layout/LineLength]
bad = cop_list.reject { |n| valid.include?(n) || valid_depts.include?(n) }
# shell out only when the list is clean:
abort "Unknown cops: #{bad.join(', ')}" unless bad.empty?

begin
  exit(RuboCop::CLI.new.run(ARGV))
rescue RuboCop::IncorrectCopNameError => e
  warn "Fix cop names: #{e.message}"
  exit 2
end

When it happens

Trigger: Running `rubocop --only Style/StringLterals` (typo), `--except Layout/LinetLength`, referencing a cop that was renamed or removed in a newer RuboCop, or naming a custom cop whose file was never required/registered before option validation runs.

Common situations: Typos in CI pipelines or in the `.rubocop` arguments file; upgrading RuboCop where cops were renamed or moved departments; using third-party cops without the corresponding `require:`/plugin entry in .rubocop.yml so they are not in the registry; stale cop lists kept in scripts.

Related errors

• -C/--cache argument must be true or false
• --%<flag>s can only be used together with --auto-gen-config.
• --disable-uncorrectable can only be used together with --aut
• Ambiguous cop name `%<name>s` used in %<origin>s needs depar
• Formatter "#{specified_key}" not found.#{suggestion}

AI-assisted analysis of rubocop/rubocop@ea712edf2b (2026-08-21). Data as JSON: /api/errors/a8616756350d1a72. Report an issue: GitHub.