What causes "The aix provider can only be used by root" in puppetlabs/puppet?

Run puppet as root (sudo puppet agent -t) — this provider simply requires euid 0.

puppetlabs/puppet · error · Puppet::Error

The aix provider can only be used by root

Error message

The aix provider can only be used by root

What it means

The AIX package provider (aix.rb:48) hard-fails its prefetch hook with Puppet::Error whenever the puppet process is not running as root (Process.euid != 0). Prefetch runs once per catalog compilation/agent run for every package resource assigned to this provider, so a single AIX package resource in the catalog makes any non-root run abort. It exists because installp/lslpp package operations on AIX are root-only.

Source

Thrown at lib/puppet/provider/package/aix.rb:48

  defaultfor 'os.name' => :aix

  attr_accessor :latest_info

  STATE_CODE = {
    'A' => :applied,
    'B' => :broken,
    'C' => :committed,
    'E' => :efix_locked,
    'O' => :obsolete,
    '?' => :inconsistent,
  }.freeze

  def self.srclistcmd(source)
    [command(:installp), "-L", "-d", source]
  end

  def self.prefetch(packages)
    raise Puppet::Error, _("The aix provider can only be used by root") if Process.euid != 0

    return unless packages.detect { |_name, package| package.should(:ensure) == :latest }

    sources = packages.collect { |_name, package| package[:source] }.uniq.compact

    updates = {}
    sources.each do |source|
      execute(srclistcmd(source)).each_line do |line|
        next unless line =~ /^[^#][^:]*:([^:]*):([^:]*)/

        current = {}
        current[:name]    = Regexp.last_match(1)
        current[:version] = Regexp.last_match(2)
        current[:source]  = source

        if updates.key?(current[:name])
          previous = updates[current[:name]]

View on GitHub (pinned to e227c27540)

Solutions

Run puppet as root (sudo puppet agent -t) — this provider simply requires euid 0.
If you only wanted to inspect packages as non-root, use `rpm -qa` / `installp -L` directly instead of the puppet provider.
If rootless puppet is a hard requirement, remove/replace the package resources using the aix provider (e.g. manage via rpm provider) so prefetch is not invoked.

Example fix

# before (as normal user): fails during prefetch
puppet resource package ensure=latest provider=aix

# after: elevate so Process.euid == 0
sudo puppet resource package ensure=latest provider=aix

Defensive patterns

Strategy: validation

Validate before calling

# only manage AIX packages when running as root
fail 'aix provider requires root (Process.euid == 0)' unless Process.euid == 0
# or in a wrapper: exec sudo puppet agent -t unless Process.uid == 0

Try / catch

begin
  packages.each { |p| p.provider.prefetch(nil) }
rescue Puppet::Error => e
  raise unless e.message == 'The aix provider can only be used by root'
  Puppet.notice 'skipping AIX package work: run agent as root'
end

Prevention

Run the puppet agent under root (or a properly privileged service account with euid 0) on AIX.
Gate AIX package profiles so inspection-only, non-root `puppet resource` sessions never touch them.
Document that prefetch of this provider is unconditional — one package resource is enough to require root.

When it happens

Trigger: Running `puppet agent -t`, `puppet apply`, or `puppet resource package` as a non-root user on an AIX node whose catalog contains at least one package resource handled by the aix provider (its should(:ensure) triggers prefetch).

Common situations: Running puppet via sudo-less cron or a non-privileged CI account; using `puppet resource package` for inspection as a normal user; agent downgraded permissions after an RBAC change on AIX.

Related errors

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