{"record":{"id":"037e38fb19435f0d","repo":"instructure/canvas-lms","slug":"unrecognized-setting-sent-to-incomingmessageprocessor-key","errorCode":null,"errorMessage":"unrecognized setting sent to IncomingMessageProcessor: #{key}","messagePattern":"unrecognized setting sent to IncomingMessageProcessor: #(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gems/incoming_mail_processor/lib/incoming_mail_processor/incoming_message_processor.rb","lineNumber":127,"sourceCode":"        MailboxClasses.fetch(account.protocol)\n      end\n\n      def timeout_method(&)\n        Canvas.timeout_protection(\"incoming_message_processor\", raise_on_timeout: true, &)\n      end\n\n      def configure_settings(config)\n        @settings = IncomingMailProcessor::Settings.new\n        @deprecated_settings = IncomingMailProcessor::DeprecatedSettings.new\n\n        config.symbolize_keys.each do |key, value|\n          if IncomingMailProcessor::Settings.members.map(&:to_sym).include?(key)\n            settings.send(:\"#{key}=\", value)\n          elsif IncomingMailProcessor::DeprecatedSettings.members.map(&:to_sym).include?(key)\n            logger&.warn(\"deprecated setting sent to IncomingMessageProcessor: #{key}\")\n            deprecated_settings.send(:\"#{key}=\", value)\n          else\n            raise \"unrecognized setting sent to IncomingMessageProcessor: #{key}\"\n          end\n        end\n      end\n\n      def configure_accounts(account_configs)\n        flat_account_configs = flatten_account_configs(account_configs)\n        self.mailbox_accounts = flat_account_configs.map do |mailbox_protocol, mailbox_config|\n          error_folder = mailbox_config.delete(:error_folder)\n          address = mailbox_config[:address] || mailbox_config[:username]\n          IncomingMailProcessor::MailboxAccount.new({\n                                                      protocol: mailbox_protocol.to_sym,\n                                                      config: mailbox_config,\n                                                      address:,\n                                                      error_folder:,\n                                                    })\n        end\n      end\n","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/instructure/canvas-lms/blob/1c9f0bb8013ed69c4f2efe11fd483025469b7e6c/gems/incoming_mail_processor/lib/incoming_mail_processor/incoming_message_processor.rb#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove or rename the offending key so it matches an entry in IncomingMailProcessor::Settings.members.","Check Canvas CHANGELOG/upgrades guide for settings that were renamed or removed after your previous version.","Replace removed deprecated settings with their new equivalents rather than relying on the warn path.","Validate the settings hash locally (compare keys against IncomingMailProcessor::Settings.members) before deploying."],"exampleFix":"// before (config)\nincoming_mail:\n  incoming_email: bot@example.com\n  legacy_queue_name: mailers   # unrecognized\n// after\nincoming_mail:\n  incoming_email: bot@example.com\n  # removed unrecognized key; check Settings.members for valid names","handlingStrategy":"validation","validationCode":"valid = IncomingMailProcessor::Settings.members.map(&:to_sym)\nunknown = settings.keys.map(&:to_sym) - valid\nraise \"unknown mail settings: #{unknown}\" unless unknown.empty?","typeGuard":null,"tryCatchPattern":"begin\n  IncomingMessageProcessor.configure(working_directory, config)\nrescue RuntimeError => e\n  raise unless e.message.start_with?('unrecognized setting sent to IncomingMessageProcessor')\n  Rails.logger.error(\"mail config has stale keys after upgrade: #{e.message}\")\n  raise\nend","preventionTips":["Compare configured keys against IncomingMailProcessor::Settings.members after every Canvas upgrade.","Treat deprecated-setting warnings as prompts to migrate before removal.","Keep mail config in version control and diff against upstream examples when upgrading."],"tags":["mail","configuration","settings","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"1c9f0bb8013ed69c4f2efe11fd483025469b7e6c","analyzedAt":"2026-09-15T20:33:18.891Z","contentChangedAt":"2026-09-15T20:33:18.891Z","schemaVersion":2},"datasetVersion":"2026-09-23T02:17:17.105Z"}