What causes "Some pre-run checks failed" in puppetlabs/puppet?

Read the agent log immediately above the raise: each failing resource logs its own exception with the specific reason

puppetlabs/puppet · error · Puppet::Error

Some pre-run checks failed

Error message

Some pre-run checks failed

What it means

Before applying a catalog, Puppet::Transaction#perform_pre_run_checks calls pre_run_check on every resource in the catalog. This hook lets resource types validate state that depends on the complete catalog (the base Puppet::Type implementation at lib/puppet/type.rb:1028 is a no-op; custom and third-party types override it). If any check raises Puppet::Error, each failure is logged per-resource via log_exception and the whole transaction aborts with 'Some pre-run checks failed' before any resource is synced.

Source

Thrown at lib/puppet/transaction.rb:90

  #
  # @see Puppet::Transaction#evaluate
  # @see Puppet::Type#pre_run_check
  # @raise [Puppet::Error] If any pre-run checks failed.
  # @return [void]
  def perform_pre_run_checks
    prerun_errors = {}

    @catalog.vertices.each do |res|
      res.pre_run_check
    rescue Puppet::Error => detail
      prerun_errors[res] = detail
    end

    unless prerun_errors.empty?
      prerun_errors.each do |res, detail|
        res.log_exception(detail)
      end
      raise Puppet::Error, _("Some pre-run checks failed")
    end
  end

  # This method does all the actual work of running a transaction.  It
  # collects all of the changes, executes them, and responds to any
  # necessary events.
  def evaluate(&block)
    block ||= method(:eval_resource)
    generator = AdditionalResourceGenerator.new(@catalog, nil, @prioritizer)
    @catalog.vertices.each { |resource| generator.generate_additional_resources(resource) }

    perform_pre_run_checks

    persistence.load if persistence.enabled?(catalog)

    Puppet.info _("Applying configuration version '%{version}'") % { version: catalog.version } if catalog.version

    continue_while = -> { !stop_processing? }

View on GitHub (pinned to e227c27540)

Solutions

Read the agent log immediately above the raise: each failing resource logs its own exception with the specific reason
Fix the underlying condition reported by that resource (e.g., restore the fstab entry or device the custom type checks)
If the check is too strict for your nodes, patch or configure the custom type/module that implements pre_run_check
Re-run with puppet agent --test --debug for the full per-resource backtrace

Defensive patterns

Strategy: try-catch

Try / catch

begin
  Puppet::Transaction.new(catalog, report).evaluate
rescue Puppet::Error => e
  if e.message == 'Some pre-run checks failed'
    report.logs.map(&:message).grep(/pre.?run|failed/).each { |m| warn m } # per-resource causes are in the logs
  else
    raise
  end
end

Prevention

Treat pre_run_check failures as fatal and surface the per-resource log lines above the raise
For custom types, keep pre_run_check narrow and message-rich: raise Puppet::Error, 'specific reason'
Smoke-test custom types on clean nodes in CI so environmental preconditions are caught before production

When it happens

Trigger: A catalog containing a custom resource type whose pre_run_check raises Puppet::Error (e.g., a mount-like type detecting a missing fstab entry, or a type verifying a peer resource exists). One bad resource fails the entire run, even if unrelated resources were healthy.

Common situations: Custom in-house types or module-provided types (often via ruby providers) enforcing cross-resource invariants; upgrading a module that adds stricter pre-run validation; node drift (missing /etc/fstab entry, absent device) that only manifests at apply time.

Related errors

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