puppetlabs/puppet · error · ArgumentError

An ssl_context is required when connecting to 'https://%{hos

Error message

An ssl_context is required when connecting to 'https://%{host}:%{port}'

What it means

The deprecated Puppet::Network::HttpPool.connection factory requires an explicit ssl_context whenever use_ssl is true; without one it raises ArgumentError naming the host and port. Older Puppet versions loaded certificates implicitly inside the pool, so code that omits the context breaks after upgrading to the explicit-verifier SSL model. A deprecation warning pointing at Puppet.runtime[:http] is emitted on every call.

Source

Thrown at lib/puppet/network/http_pool.rb:64

  # Retrieve a connection for the given host and port.
  #
  # @param host [String] The host to connect to
  # @param port [Integer] The port to connect to
  # @param use_ssl [Boolean] Whether to use SSL, defaults to `true`.
  # @param ssl_context [Puppet::SSL:SSLContext, nil] The ssl context to use
  #   when making HTTPS connections. Required when `use_ssl` is `true`.
  # @return [Puppet::Network::HTTP::Connection]
  #
  # @deprecated Use {Puppet.runtime[:http]} instead.
  # @api public
  #
  def self.connection(host, port, use_ssl: true, ssl_context: nil)
    Puppet.warn_once('deprecations', self, "The method 'Puppet::Network::HttpPool.connection' is deprecated. Use Puppet.runtime[:http] instead")

    if use_ssl
      unless ssl_context
        # TRANSLATORS 'ssl_context' is an argument and should not be translated
        raise ArgumentError, _("An ssl_context is required when connecting to 'https://%{host}:%{port}'") % { host: host, port: port }
      end

      verifier = Puppet::SSL::Verifier.new(host, ssl_context)
      http_client_class.new(host, port, use_ssl: true, verifier: verifier)
    else
      if ssl_context
        # TRANSLATORS 'ssl_context' is an argument and should not be translated
        Puppet.warning(_("An ssl_context is unnecessary when connecting to 'http://%{host}:%{port}' and will be ignored") % { host: host, port: port })
      end

      http_client_class.new(host, port, use_ssl: false)
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Pass ssl_context: Puppet.lookup(:ssl_context) once SSL has been initialized in this process
2. Better: migrate to the supported client Puppet.runtime[:http] (Puppet::HTTP::Client), which manages SSL contexts itself
3. For plain HTTP pass use_ssl: false (a stray ssl_context then only triggers a warning)
4. Wrap connection creation in a single helper so the upgrade touches one place

Example fix

# before
conn = Puppet::Network::HttpPool.connection('puppet', 8140)

# after
ssl_context = Puppet::SSL::SSLProvider.new.load_ssl_context
conn = Puppet::Network::HttpPool.connection('puppet', 8140, ssl_context: ssl_context)

def https_connection(host, port, ssl_context)
  raise ArgumentError, 'ssl_context is required for https connections' if ssl_context.nil?
  Puppet::Network::HttpPool.connection(host, port, ssl_context: ssl_context)
end

When it happens

Trigger: Puppet::Network::HttpPool.connection('puppet', 8140) with the default use_ssl: true and no ssl_context, as written by Puppet 4-era helper code, CA-store utilities, or tooling that calls the agent's HttpPool directly.

Common situations: Upgrades to Puppet 5+: SSL setup became caller-supplied (ssl_context obtained via Puppet.lookup(:ssl_context) or the SSLProvider). Scripts and embedded apps that relied on implicit certificate loading stop working.

Related errors

• Expected an instance of Puppet::SSL::Verifier but was passed
• Run `puppet agent -t`
• PathPatterns cannot be created with a zero byte.
• Request to Puppet Forge failed. Detail: %{detail}.
• An action must be specified.

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