instructure/canvas-lms · error

unrecognized setting sent to IncomingMessageProcessor: #

Error message

unrecognized setting sent to IncomingMessageProcessor: #{key}

What it means

IncomingMessageProcessor#configure_settings validates every settings key against the Datamappify-style Settings and DeprecatedSettings members. Unknown keys indicate a stale or misspelled configuration and raise hard, while deprecated keys only warn — forcing operators to migrate off obsolete settings.

Solutions

1. Remove or rename the offending key so it matches an entry in IncomingMailProcessor::Settings.members.
2. Check Canvas CHANGELOG/upgrades guide for settings that were renamed or removed after your previous version.
3. Replace removed deprecated settings with their new equivalents rather than relying on the warn path.
4. Validate the settings hash locally (compare keys against IncomingMailProcessor::Settings.members) before deploying.

Example fix

// before (config)
incoming_mail:
  incoming_email: bot@example.com
  legacy_queue_name: mailers   # unrecognized
// after
incoming_mail:
  incoming_email: bot@example.com
  # removed unrecognized key; check Settings.members for valid names

valid = IncomingMailProcessor::Settings.members.map(&:to_sym)
unknown = settings.keys.map(&:to_sym) - valid
raise "unknown mail settings: #{unknown}" unless unknown.empty?

begin
  IncomingMessageProcessor.configure(working_directory, config)
rescue RuntimeError => e
  raise unless e.message.start_with?('unrecognized setting sent to IncomingMessageProcessor')
  Rails.logger.error("mail config has stale keys after upgrade: #{e.message}")
  raise
end

When it happens

Trigger: Calling IncomingMessageProcessor.configure with a settings hash containing a key not in Settings/DeprecatedSettings — e.g. renamed settings after a Canvas upgrade, typos like 'incomming' instead of 'incoming', or leftover keys from an old config file.

Common situations: Upgrading Canvas without updating config/incoming_mail.yml or canvas console.yml mail settings; copying config from a third-party fork with extra keys; hand-edited YAML typos; deprecated keys eventually removed after the deprecation window.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Folder # does not exist.
• invalid options - # (must be in # )
• Peer reviews are not enabled for this assignment
• A course did not pass validation
• A # user did not pass validation (user: # , # : # , error…

AI-assisted analysis of instructure/canvas-lms@1c9f0bb801 (2026-09-15). Data as JSON: /api/errors/037e38fb19435f0d. Report an issue: GitHub.

Appendix: source

Thrown at gems/incoming_mail_processor/lib/incoming_mail_processor/incoming_message_processor.rb:127

        MailboxClasses.fetch(account.protocol)
      end

      def timeout_method(&)
        Canvas.timeout_protection("incoming_message_processor", raise_on_timeout: true, &)
      end

      def configure_settings(config)
        @settings = IncomingMailProcessor::Settings.new
        @deprecated_settings = IncomingMailProcessor::DeprecatedSettings.new

        config.symbolize_keys.each do |key, value|
          if IncomingMailProcessor::Settings.members.map(&:to_sym).include?(key)
            settings.send(:"#{key}=", value)
          elsif IncomingMailProcessor::DeprecatedSettings.members.map(&:to_sym).include?(key)
            logger&.warn("deprecated setting sent to IncomingMessageProcessor: #{key}")
            deprecated_settings.send(:"#{key}=", value)
          else
            raise "unrecognized setting sent to IncomingMessageProcessor: #{key}"
          end
        end
      end

      def configure_accounts(account_configs)
        flat_account_configs = flatten_account_configs(account_configs)
        self.mailbox_accounts = flat_account_configs.map do |mailbox_protocol, mailbox_config|
          error_folder = mailbox_config.delete(:error_folder)
          address = mailbox_config[:address] || mailbox_config[:username]
          IncomingMailProcessor::MailboxAccount.new({
                                                      protocol: mailbox_protocol.to_sym,
                                                      config: mailbox_config,
                                                      address:,
                                                      error_folder:,
                                                    })
        end
      end

View on GitHub (pinned to 1c9f0bb801)