puppetlabs/puppet · error · Puppet::Error

Environment '%{environment}' not found on server, aborting r

Error message

Environment '%{environment}' not found on server, aborting run.

What it means

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.

Source

Thrown at lib/puppet/configurer.rb:540

    report.cached_catalog_status ||= @cached_catalog_status
    report.add_times(:total, Time.now - report.time)
    report.finalize_report
    Puppet::Util::Log.close(report)
    send_report(report)
    Puppet.pop_context
  end
  private :run_internal

  def valid_server_environment?
    session = Puppet.lookup(:http_session)
    begin
      fs = session.route_to(:fileserver)
      fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: @environment) # rubocop:disable Lint/BooleanSymbol
      true
    rescue Puppet::HTTP::ResponseError => detail
      if detail.response.code == 404
        if Puppet[:strict_environment_mode]
          raise Puppet::Error, _("Environment '%{environment}' not found on server, aborting run.") % { environment: @environment }
        else
          Puppet.notice(_("Environment '%{environment}' not found on server, skipping initial pluginsync.") % { environment: @environment })
        end
      else
        Puppet.log_exception(detail, detail.message)
      end
      false
    rescue => detail
      Puppet.log_exception(detail, detail.message)
      false
    end
  end

  def find_functional_server
    begin
      session = Puppet.lookup(:http_session)
      service = session.route_to(:puppet)
      return [service.url.host, service.url.port]

View on GitHub (pinned to e227c27540)

Solutions

1. Deploy the environment on the server (`r10k deploy environment <env> -p` or place the directory under environments/)
2. Fix the agent's setting: `puppet config set environment <correct_env>`
3. Verify the agent targets the intended server (server/port in puppet.conf)
4. Only if intentional for your workflow: remove strict_environment_mode, which downgrades the miss to a notice and skips initial pluginsync

Example fix

# before (agent puppet.conf)
[agent]
environment = produktion
strict_environment_mode = true
# after
[agent]
environment = production
strict_environment_mode = true

# probe the fileserver for this environment before running the agent
session = Puppet.lookup(:http_session)
fs = session.route_to(:fileserver)
begin
  fs.get_file_metadatas(path: URI(Puppet[:pluginsource]).path, recurse: :false, environment: Puppet[:environment])
rescue Puppet::HTTP::ResponseError => e
  abort "environment '#{Puppet[:environment]}' not present on server" if e.response.code == 404
  raise
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Catalog environment didn't stabilize after %{tries} fetches,
• Failed to retrieve %{name}: %{detail}
• Invalid environment mode '%{mode_name}'
• Could not retrieve local facts: %{detail}
• Find %{uri} resulted in 404 with the message: %{body}

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/d77b9873c3f1e5fe. Report an issue: GitHub.