{"record":{"id":"d5c22483940cce2d","repo":"puppetlabs/puppet","slug":"invalid-environment-mode-mode-name","errorCode":null,"errorMessage":"Invalid environment mode '%{mode_name}'","messagePattern":"Invalid environment mode '%(.+?)'","errorType":"validation","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/application.rb","lineNumber":307,"sourceCode":"      require_relative '../puppet/util/run_mode'\n      @run_mode = Puppet::Util::RunMode[mode_name || Puppet.settings.preferred_run_mode]\n    end\n\n    # Sets environment_mode name. When acting as a compiler, the environment mode\n    # should be `:local` since the directory must exist to compile the catalog.\n    # When acting as an agent, the environment mode should be `:remote` since\n    # the Puppet[:environment] setting refers to an environment directoy on a remote\n    # system. The `:not_required` mode is for cases where the application does not\n    # need an environment to run.\n    #\n    # @param mode_name [Symbol] The name of the environment mode to run in. May\n    #   be one of `:local`, `:remote`, or `:not_required`. This impacts where the\n    #   application looks for its specified environment. If `:not_required` or\n    #   `:remote` are set, the application will not fail if the environment does\n    #   not exist on the local filesystem.\n    # @api public\n    def environment_mode(mode_name)\n      raise Puppet::Error, _(\"Invalid environment mode '%{mode_name}'\") % { mode_name: mode_name } unless [:local, :remote, :not_required].include?(mode_name)\n\n      @environment_mode = mode_name\n    end\n\n    # Gets environment_mode name. If none is set with `environment_mode=`,\n    # default to :local.\n    # @return [Symbol] The current environment mode\n    # @api public\n    def get_environment_mode\n      @environment_mode || :local\n    end\n\n    # This is for testing only\n    # @api public\n    def clear_everything_for_tests\n      @run_mode = @banner = @run_status = @option_parser_commands = nil\n    end\n  end","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/application.rb#L289-L325","documentation":"Puppet::Application#environment_mode is a validating setter: it accepts only :local, :remote, or :not_required and raises Puppet::Error at call time for anything else. :local (the default when never called) requires the environment to exist on the local filesystem; :remote and :not_required are for agents and apps that do not need a local environment.","triggerScenarios":"An application subclass calling environment_mode with an unsupported value — environment_mode(:none), a string 'local' instead of the symbol, or a typo'd constant that evaluates to nil.","commonSituations":"Custom puppet applications copied from old examples using different mode names; refactors changing the argument; configuration-driven strings passed straight through without to_sym.","solutions":["Pass one of :local, :remote, :not_required as a symbol","If no special mode is needed, simply do not call environment_mode — it defaults to :local","Coerce config-driven strings with .to_sym and validate membership before calling"],"exampleFix":"# before\nenvironment_mode(:none)\n\n# after\nenvironment_mode(:not_required)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"VALID_ENV_MODES = [:local, :remote, :not_required].freeze\ndef environment_mode!(mode)\n  raise ArgumentError, \"bad mode #{mode}\" unless VALID_ENV_MODES.include?(mode)\n  app.environment_mode(mode)\nend","tryCatchPattern":null,"preventionTips":["Always pass symbols, never strings — coerce with .to_sym at the boundary","Keep the allowed list in one constant shared by all callers","Fail fast at app definition time, not at first environment resolution"],"tags":["application","environment","enum","puppet"],"backgroundTag":"invalid-enum-value","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}