puppetlabs/puppet · error · ArgumentError

Could not find terminus %{terminus_class} for indirection %{

Error message

Could not find terminus %{terminus_class} for indirection %{indirection}

What it means

make_terminus resolves the terminus class again when instantiating a terminus (called from Indirection#terminus); if Puppet::Indirector::Terminus.terminus_class returns nil it raises ArgumentError 'Could not find terminus ... for indirection ...'. This fires when the setting changed after validation or when code requests a terminus by name that is not loadable in the current process.

Source

Thrown at lib/puppet/indirector/indirection.rb:376

  # @return [Puppet::Indirector::Terminus] terminus instance (usually a subclass
  #   of Puppet::Indirector::Terminus) for this request
  def prepare(request)
    # Pick our terminus.
    terminus_name = terminus_class

    dest_terminus = terminus(terminus_name)
    check_authorization(request, dest_terminus)
    dest_terminus.validate(request)

    dest_terminus
  end

  # Create a new terminus instance.
  def make_terminus(terminus_class)
    # Load our terminus class.
    klass = Puppet::Indirector::Terminus.terminus_class(name, terminus_class)
    unless klass
      raise ArgumentError, _("Could not find terminus %{terminus_class} for indirection %{indirection}") % { terminus_class: terminus_class, indirection: name }
    end

    klass.new
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Same check as at assignment time: confirm Puppet::Indirector::Terminus.terminus_classes(<indirection>) actually lists the name in this process.
2. Install or require the gem/module providing the terminus on the host running the code.
3. Prefer the validated path (indirection.terminus_class = name) over direct terminus(name) lookups.
4. Add a boot-time smoke test that requires the terminus file so failures surface at startup with a clear message.

Example fix

# before
terminus = Puppet::Resource::Catalog.indirection.terminus(:custom)
# ArgumentError: Could not find terminus custom for indirection catalog

# after
gem 'puppet-catalog-custom' # installed and required first
Puppet::Resource::Catalog.indirection.terminus(:custom)

name = :json
unless Puppet::Indirector::Terminus.terminus_class(indirection.name, name)
  raise ArgumentError, 'cannot instantiate missing terminus: ' + name.to_s
end
indirection.terminus(name)

When it happens

Trigger: Ruby code calling indirection.terminus(:some_name) with a name that is not registered for that indirection; a terminus file removed or its gem uninstalled between configuration and use; a custom terminus whose require fails lazily so terminus_class returns nil.

Common situations: Pluginsync-delivered termini present on agents but not on compile servers; gems uninstalled during cleanup; name case mismatches (Json vs json); half-completed upgrades where config references a terminus only shipped in the newer gem.

Related errors

• Could not find terminus %{terminus_class} for indirection %{
• Invalid terminus name %{terminus_class}
• Listing remote file buckets is not allowed
• Could not find %{request} to destroy
• Could not read MessagePack data for %{indirection} %{key}: %

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