puppetlabs/puppet · error · Puppet::Error

Unable to read overrides plist, too many attempts

Error message

Unable to read overrides plist, too many attempts

What it means

The launchd provider reads the launchd overrides plist (the path returned by launchd_overrides, e.g. /var/db/launchd.db/com.apple.launchd/overrides.plist) through Puppet::Util::Plist. read_plist returns nil when the file cannot be parsed; read_overrides retries up to 20 times with a 0.1s sleep (~2 seconds total) and raises when every attempt yields nil.

Source

Thrown at lib/puppet/provider/service/launchd.rb:215

    end
    @job_list
  end

  # Read a plist, whether its format is XML or in Apple's "binary1"
  # format.
  def self.read_plist(path)
    Puppet::Util::Plist.read_plist_file(path)
  end

  # Read overrides plist, retrying if necessary
  def self.read_overrides
    i = 1
    overrides = nil
    loop do
      Puppet.debug(_("Reading overrides plist, attempt %{i}") % { i: i }) if i > 1
      overrides = read_plist(launchd_overrides)
      break unless overrides.nil?
      raise Puppet::Error, _('Unable to read overrides plist, too many attempts') if i == 20

      Puppet.info(_('Overrides file could not be read, trying again.'))
      Kernel.sleep(0.1)
      i += 1
    end
    overrides
  end

  # Clean out the @property_hash variable containing the cached list of services
  def flush
    @property_hash.clear
  end

  def exists?
    Puppet.debug("Puppet::Provider::Launchd:Ensure for #{@property_hash[:name]}: #{@property_hash[:ensure]}")
    @property_hash[:ensure] != :absent
  end

View on GitHub (pinned to e227c27540)

Solutions

1. Verify the file exists at the path in the error's context: ls -l /var/db/launchd.db/com.apple.launchd/
2. Validate the plist: plutil -lint on the overrides file
3. Restore a known-good copy from backup/TM snapshot, or let launchd regenerate it by toggling a job's disabled state once interactively
4. Check permissions/ownership (root:wheel, readable) so the agent-side parse succeeds

plutil -lint /var/db/launchd.db/com.apple.launchd/overrides.plist \
  || echo "overrides plist invalid — restore before puppet run"

When it happens

Trigger: self.read_overrides is called during prefetch/flush of launchd services when the overrides file is missing, empty, or not a valid plist (XML or binary1), so Puppet::Util::Plist.read_plist_file keeps returning nil across all 20 attempts.

Common situations: Freshly imaged Macs that never generated an overrides file; the plist corrupted by a bad write or truncated sync tool; macOS upgrades relocating the database; configuration-management tools other than Puppet having clobbered the file.

Related errors

• Unable to find launchd plist for job: #{label}
• Unable to parse launchd plist at path: #{job_path}
• puppet.plans/invalid-name
• launchctl list failed to return any data.
• Unknown plist format #{format}

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