puppetlabs/puppet · error · Puppet::Error

Unrecognized option(s): %{opts}

Error message

Unrecognized option(s): %{opts}

What it means

Puppet::Network::HTTP::Connection's constructor accepts only a fixed option set defined by OPTION_DEFAULTS: :use_ssl, :verifier and :redirect_limit. Any other key in the options hash raises Puppet::Error listing the unrecognized options (sorted, inspected). This hard validation replaced the lenient option handling of older Puppet versions when the HTTP stack was reworked.

Source

Thrown at lib/puppet/network/http/connection.rb:49

  # @param port [Integer] the port to which this client will connect to
  # @param options [Hash] options influencing the properties of the created
  #   connection,
  # @option options [Boolean] :use_ssl true to connect with SSL, false
  #   otherwise, defaults to true
  # @option options [Puppet::SSL::Verifier] :verifier An object that will configure
  #   any verification to do on the connection
  # @option options [Integer] :redirect_limit the number of allowed
  #   redirections, defaults to 10 passing any other option in the options
  #   hash results in a Puppet::Error exception
  #
  # @note the HTTP connection itself happens lazily only when {#request}, or
  #   one of the {#get}, {#post}, {#delete}, {#head} or {#put} is called
  # @note The correct way to obtain a connection is to use one of the factory
  #   methods on {Puppet::Network::HttpPool}
  # @api private
  def initialize(host, port, options = {})
    unknown_options = options.keys - OPTION_DEFAULTS.keys
    raise Puppet::Error, _("Unrecognized option(s): %{opts}") % { opts: unknown_options.map(&:inspect).sort.join(', ') } unless unknown_options.empty?

    options = OPTION_DEFAULTS.merge(options)
    @use_ssl = options[:use_ssl]
    if @use_ssl
      unless options[:verifier].is_a?(Puppet::SSL::Verifier)
        raise ArgumentError, _("Expected an instance of Puppet::SSL::Verifier but was passed a %{klass}") % { klass: options[:verifier].class }
      end

      @verifier = options[:verifier]
    end
    @redirect_limit = options[:redirect_limit]
    @site = Puppet::HTTP::Site.new(@use_ssl ? 'https' : 'http', host, port)
    @client = Puppet.runtime[:http]
  end

  # The address to connect to.
  def address
    @site.host

View on GitHub (pinned to e227c27540)

Solutions

1. Remove the unsupported keys; the accepted options are use_ssl, verifier and redirect_limit
2. Replace verify: false by passing a Puppet::SSL::Verifier (or use_ssl: false for plain HTTP)
3. Migrate to the non-deprecated Puppet.runtime[:http] client, which takes these concerns differently
4. Check OPTION_DEFAULTS in lib/puppet/network/http/connection.rb for your Puppet version before passing options

Example fix

# before
conn = Puppet::Network::HTTP::Connection.new('puppet', 8140, verify: false)

# after
verifier = Puppet::SSL::Verifier.new('puppet', ssl_context)
conn = Puppet::Network::HTTP::Connection.new('puppet', 8140, use_ssl: true, verifier: verifier)

ALLOWED_OPTIONS = %i[use_ssl verifier redirect_limit].freeze

options.each_key do |k|
  raise ArgumentError, "unsupported option #{k.inspect}" unless ALLOWED_OPTIONS.include?(k)
end
Puppet::Network::HTTP::Connection.new(host, port, options)

When it happens

Trigger: Calling Puppet::Network::HTTP::Connection.new(host, port, verify: false) or passing legacy keys like :ssl_context or timeout settings; reusing Puppet 4-era HttpPool option hashes verbatim against this class.

Common situations: Upgrading Puppet 4 to 5/6 where the internal HTTP API changed; copy-pasted connection code from old blog posts; scripts trying to disable SSL verification the old way.

Related errors

• Unknown arguments: %{args}
• Cannot disable unrecognized warning types '%{invalid}'. Vali
• Invalid value '%{value}' for parameter %{name}. Allowed valu
• Errors while validating epp
• One or more file(s) specified did not exist: %{files}

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