puppetlabs/puppet · error · Puppet::Network::HTTP::Error::HTTPBadRequestError

An environment parameter must be specified

Error message

An environment parameter must be specified

What it means

Every request to a v3 indirected route must carry an environment query parameter. The handler removes it from params with params.delete(:environment) and then checks it; if it is absent, the request fails with HTTP 400 'An environment parameter must be specified'. The environment selects which manifest and module set the master uses to answer the request.

Source

Thrown at lib/puppet/network/http/api/indirected_routes.rb:86

    # this also depluralizes the indirection_name if it is a search
    method = indirection_method(http_method, indirection_name)

    # check whether this indirection matches the prefix and version in the
    # request
    if url_prefix != IndirectionType.url_prefix_for(indirection_name)
      raise Puppet::Network::HTTP::Error::HTTPBadRequestError, _("Indirection '%{indirection_name}' does not match url prefix '%{url_prefix}'") % { indirection_name: indirection_name, url_prefix: url_prefix }
    end

    indirection = Puppet::Indirector::Indirection.instance(indirection_name.to_sym)
    unless indirection
      raise Puppet::Network::HTTP::Error::HTTPNotFoundError.new(
        _("Could not find indirection '%{indirection_name}'") % { indirection_name: indirection_name },
        Puppet::Network::HTTP::Issues::HANDLER_NOT_FOUND
      )
    end

    unless environment
      raise Puppet::Network::HTTP::Error::HTTPBadRequestError, _("An environment parameter must be specified")
    end

    unless Puppet::Node::Environment.valid_name?(environment)
      raise Puppet::Network::HTTP::Error::HTTPBadRequestError, _("The environment must be purely alphanumeric, not '%{environment}'") % { environment: environment }
    end

    configured_environment = Puppet.lookup(:environments).get(environment)
    unless configured_environment.nil?
      configured_environment = configured_environment.override_from_commandline(Puppet.settings)
      params[:environment] = configured_environment
    end

    if configured_environment.nil? && indirection.terminus.require_environment?
      raise Puppet::Network::HTTP::Error::HTTPNotFoundError, _("Could not find environment '%{environment}'") % { environment: environment }
    end

    params.delete(:bucket_path)

View on GitHub (pinned to e227c27540)

Solutions

1. Append ?environment=production (or the target environment) to the request URL
2. In client code always pass it explicitly, e.g. conn.get("/puppet/v3/catalog/#{certname}", environment: Puppet[:environment])
3. Verify no proxy/rewrite rule strips the query string before the request reaches the master

Example fix

# before
curl "https://puppet.example.com:8140/puppet/v3/catalog/mynode"

# after
curl "https://puppet.example.com:8140/puppet/v3/catalog/mynode?environment=production"

def build_indirected_url(indirection, key, environment)
  raise ArgumentError, 'environment is required' if environment.nil? || environment.to_s.empty?
  "/puppet/v3/#{indirection}/#{key}?environment=#{environment}"
end

When it happens

Trigger: GET /puppet/v3/catalog/mynode with no ?environment=..., PUT /puppet/v3/report/mynode without the query parameter, or a custom client that sends the environment as a header or in the body instead of the query string.

Common situations: Raw curl calls that copy the path but drop the query string; scripts ported from the v2 API where the environment was part of the path; clients that misname the parameter (env= instead of environment=); proxies that discard the query string on rewrite.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• No request key specified in %{uri}
• The indirection name must be purely alphanumeric, not '%{ind
• Indirection '%{indirection_name}' does not match url prefix
• The environment must be purely alphanumeric, not '%{environm
• The request body is invalid: %{message}

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