puppetlabs/puppet · error · Puppet::Error

Unrecognized option(s)

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.

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
• a data type must have an interface
• ads_object must be an IAdsUser or IAdsGroup instance
• An empty mode string is illegal
• An ssl_context is required when connecting to 'https://

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

Appendix: 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)