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

The environment must be purely alphanumeric, not '%{environm

Error message

The environment must be purely alphanumeric, not '%{environment}'

What it means

Before resolving an environment, the handler checks Puppet::Node::Environment.valid_name?, which only accepts word characters (letters, digits, underscore) via /\A\w+\Z/. Environment names containing dashes, dots, slashes or any other punctuation are rejected with HTTP 400. This guards the filesystem-backed environment lookup against malformed and path-traversal names.

Source

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

    # 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)

    if key == "" or key.nil?
      raise Puppet::Network::HTTP::Error::HTTPBadRequestError, _("No request key specified in %{uri}") % { uri: uri }
    end

View on GitHub (pinned to e227c27540)

Solutions

Rename the environment so it contains only letters, digits and underscores (my_env, not my-env)
If environments come from branch names, sanitize them when deploying (r10k/code-manager mapping) instead of passing raw branch names
Fix the agent's environment setting in puppet.conf so it sends a valid name
Normalize or reject suspicious environment values at the edge if the API is exposed to untrusted clients

Example fix

# before (branch name with slash and dash used directly)
curl "https://puppet:8140/puppet/v3/catalog/mynode?environment=feature/x-1"

# after (branch mapped to a safe environment name on deploy)
curl "https://puppet:8140/puppet/v3/catalog/mynode?environment=feature_x_1"

Defensive patterns

Strategy: validation

Validate before calling

def valid_environment_name?(name)
  name.is_a?(String) && name.match(/\A\w+\Z/)
end

raise ArgumentError, "invalid environment name #{env.inspect}" unless valid_environment_name?(env)

Type guard

def valid_environment_name?(name)
  name.is_a?(String) && name.match(/\A\w+\Z/)
end

Prevention

Enforce word-character naming when branch-based environments are created (r10k hooks, ENCs)
Validate environment names at the edge instead of relying on the API 400 to catch them

When it happens

Trigger: Requests with environment=my-env (dash), environment=prod.example.com (dot) or environment=../../etc (traversal attempt); an agent whose environment setting was derived from a git branch name containing '-' or '/'.

Common situations: Sites naming environments after git branches that contain dashes or slashes; environment names copied from hostnames/DNS labels with dots; automated scanners probing the API with relative paths. Environment directory names on the master must be alphanumeric/underscore for the API to accept them.

Related errors

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