{"record":{"id":"d77b9873c3f1e5fe","repo":"puppetlabs/puppet","slug":"environment-environment-not-found-on-server","errorCode":null,"errorMessage":"Environment '%{environment}' not found on server, aborting run.","messagePattern":"Environment '%(.+?)' not found on server, aborting run\\.","errorType":"exception","errorClass":"Puppet::Error","httpStatus":404,"severity":"error","filePath":"lib/puppet/configurer.rb","lineNumber":540,"sourceCode":"    report.cached_catalog_status ||= @cached_catalog_status\n    report.add_times(:total, Time.now - report.time)\n    report.finalize_report\n    Puppet::Util::Log.close(report)\n    send_report(report)\n    Puppet.pop_context\n  end\n  private :run_internal\n\n  def valid_server_environment?\n    session = Puppet.lookup(:http_session)\n    begin\n      fs = session.route_to(:fileserver)\n      fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: @environment) # rubocop:disable Lint/BooleanSymbol\n      true\n    rescue Puppet::HTTP::ResponseError => detail\n      if detail.response.code == 404\n        if Puppet[:strict_environment_mode]\n          raise Puppet::Error, _(\"Environment '%{environment}' not found on server, aborting run.\") % { environment: @environment }\n        else\n          Puppet.notice(_(\"Environment '%{environment}' not found on server, skipping initial pluginsync.\") % { environment: @environment })\n        end\n      else\n        Puppet.log_exception(detail, detail.message)\n      end\n      false\n    rescue => detail\n      Puppet.log_exception(detail, detail.message)\n      false\n    end\n  end\n\n  def find_functional_server\n    begin\n      session = Puppet.lookup(:http_session)\n      service = session.route_to(:puppet)\n      return [service.url.host, service.url.port]","sourceCodeStart":522,"sourceCodeEnd":558,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/configurer.rb#L522-L558","documentation":"Raised by `Puppet::Configurer#valid_server_environment?` during the pre-pluginsync probe: the agent requested file metadatas for the pluginsource path under the node's environment from the server's fileserver and received HTTP 404. With `strict_environment_mode = true` a missing environment is fatal and the run aborts immediately, because the agent refuses to operate in any environment other than the one it requested. Without strict mode the same 404 downgrades to a notice and initial pluginsync is skipped.","triggerScenarios":"A configurer run (`puppet agent -t` or a daemon run) with `strict_environment_mode = true` in puppet.conf while the server has no environment of that name: `fs.get_file_metadatas(... environment: @environment)` returns 404 and the `detail.response.code == 404` branch raises.","commonSituations":"Typo'd environment in agent puppet.conf; r10k deploy not yet run so the environment dir is absent; environment deleted on the server but agents still pinned to it; multi-master setups where only some compile masters have the environment.","solutions":["Deploy the environment on the server (`r10k deploy environment <env> -p` or place the directory under environments/)","Fix the agent's setting: `puppet config set environment <correct_env>`","Verify the agent targets the intended server (server/port in puppet.conf)","Only if intentional for your workflow: remove strict_environment_mode, which downgrades the miss to a notice and skips initial pluginsync"],"exampleFix":"# before (agent puppet.conf)\n[agent]\nenvironment = produktion\nstrict_environment_mode = true\n# after\n[agent]\nenvironment = production\nstrict_environment_mode = true","handlingStrategy":"validation","validationCode":"# probe the fileserver for this environment before running the agent\nsession = Puppet.lookup(:http_session)\nfs = session.route_to(:fileserver)\nbegin\n  fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: Puppet[:environment])\nrescue Puppet::HTTP::ResponseError => e\n  abort \"environment '#{Puppet[:environment]}' not present on server\" if e.response.code == 404\n  raise\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Automate environment deployment (r10k) before pinning agents to a new environment","Use `puppet config set environment <env>` rather than hand-editing to avoid typos","With strict_environment_mode on, treat a missing environment as a hard CI gate"],"tags":["puppet-agent","environment","strict-environment-mode","http-404","pluginsync"],"backgroundTag":"environment-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}