{"record":{"id":"5e4dccb7b6615f14","repo":"puppetlabs/puppet","slug":"an-ssl-context-is-required-when-connecting-to-htt","errorCode":null,"errorMessage":"An ssl_context is required when connecting to 'https://%{host}:%{port}'","messagePattern":"An ssl_context is required when connecting to 'https://%(.+?):%(.+?)'","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/puppet/network/http_pool.rb","lineNumber":64,"sourceCode":"  # Retrieve a connection for the given host and port.\n  #\n  # @param host [String] The host to connect to\n  # @param port [Integer] The port to connect to\n  # @param use_ssl [Boolean] Whether to use SSL, defaults to `true`.\n  # @param ssl_context [Puppet::SSL:SSLContext, nil] The ssl context to use\n  #   when making HTTPS connections. Required when `use_ssl` is `true`.\n  # @return [Puppet::Network::HTTP::Connection]\n  #\n  # @deprecated Use {Puppet.runtime[:http]} instead.\n  # @api public\n  #\n  def self.connection(host, port, use_ssl: true, ssl_context: nil)\n    Puppet.warn_once('deprecations', self, \"The method 'Puppet::Network::HttpPool.connection' is deprecated. Use Puppet.runtime[:http] instead\")\n\n    if use_ssl\n      unless ssl_context\n        # TRANSLATORS 'ssl_context' is an argument and should not be translated\n        raise ArgumentError, _(\"An ssl_context is required when connecting to 'https://%{host}:%{port}'\") % { host: host, port: port }\n      end\n\n      verifier = Puppet::SSL::Verifier.new(host, ssl_context)\n      http_client_class.new(host, port, use_ssl: true, verifier: verifier)\n    else\n      if ssl_context\n        # TRANSLATORS 'ssl_context' is an argument and should not be translated\n        Puppet.warning(_(\"An ssl_context is unnecessary when connecting to 'http://%{host}:%{port}' and will be ignored\") % { host: host, port: port })\n      end\n\n      http_client_class.new(host, port, use_ssl: false)\n    end\n  end\nend\n","sourceCodeStart":46,"sourceCodeEnd":79,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/network/http_pool.rb#L46-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass ssl_context: Puppet.lookup(:ssl_context) once SSL has been initialized in this process","Better: migrate to the supported client Puppet.runtime[:http] (Puppet::HTTP::Client), which manages SSL contexts itself","For plain HTTP pass use_ssl: false (a stray ssl_context then only triggers a warning)","Wrap connection creation in a single helper so the upgrade touches one place"],"exampleFix":"# before\nconn = Puppet::Network::HttpPool.connection('puppet', 8140)\n\n# after\nssl_context = Puppet::SSL::SSLProvider.new.load_ssl_context\nconn = Puppet::Network::HttpPool.connection('puppet', 8140, ssl_context: ssl_context)","handlingStrategy":"validation","validationCode":"def https_connection(host, port, ssl_context)\n  raise ArgumentError, 'ssl_context is required for https connections' if ssl_context.nil?\n  Puppet::Network::HttpPool.connection(host, port, ssl_context: ssl_context)\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Initialize SSL (load client cert and CA) before any HTTPS helper call","Prefer Puppet.runtime[:http]; it removes the manual context plumbing","Grep the codebase for HttpPool.connection when upgrading Puppet - it is deprecated"],"tags":["ssl","http-client","missing-parameter","deprecation"],"backgroundTag":"missing-ssl-context","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}