What causes "Failed to diff files" in puppetlabs/puppet?

Supply the first side — checksum_a or file_a — e.g. Dipper#diff(sum_a, sum_b, nil, nil)

puppetlabs/puppet · error · Puppet::Error

Failed to diff files

Error message

Failed to diff files

What it means

At the end of Dipper#diff, a guard raises Puppet::Error 'Failed to diff files' unless a file_diff result was produced. The usual path is passing neither checksum_a nor file_a, so no comparison branch executed and file_diff stayed nil; the argument-order mistakes of the four-parameter signature are the practical cause.

Source

Thrown at lib/puppet/file_bucket/dipper.rb:101

        end
      else
        raise Puppet::Error, _("Please provide a file or checksum to diff with")
      end
    elsif file_a
      if checksum_b
        tmp_file = ::Tempfile.new('diff')
        begin
          restore(tmp_file.path, checksum_b)
          file_diff = Puppet::Util::Diff.diff(file_a, tmp_file.path)
        ensure
          tmp_file.close
          tmp_file.unlink
        end
      elsif file_b
        file_diff = Puppet::Util::Diff.diff(file_a, file_b)
      end
    end
    raise Puppet::Error, _("Failed to diff files") unless file_diff

    file_diff.to_s
  end

  # Retrieves a file by sum.
  def getfile(sum)
    get_bucket_file(sum).to_s
  end

  # Retrieves a FileBucket::File by sum.
  def get_bucket_file(sum)
    source_path = "#{@rest_path}#{@checksum_type}/#{sum}"
    file_bucket_file = Puppet::FileBucket::File.indirection.find(source_path, :bucket_path => @local_path)

    raise Puppet::Error, _("File not found") unless file_bucket_file

    file_bucket_file
  end

View on GitHub (pinned to e227c27540)

Solutions

Supply the first side — checksum_a or file_a — e.g. Dipper#diff(sum_a, sum_b, nil, nil)
Review the signature: diff(checksum_a, checksum_b, file_a, file_b) and check `puppet filebucket help diff`
Fail fast before calling: raise unless checksum_a || file_a

Example fix

# before
dipper.diff(nil, nil, '/tmp/a', '/tmp/b') # wait -- this works; the broken form is:
dipper.diff(nil, sum_b, nil, nil)
# after
dipper.diff(nil, nil, '/tmp/a', '/tmp/b') # file_a + file_b

Defensive patterns

Strategy: validation

Validate before calling

raise ArgumentError, 'diff needs checksum_a or file_a' if checksum_a.nil? && file_a.nil?
file_diff = dipper.diff(checksum_a, checksum_b, file_a, file_b)

Prevention

Keyword-argument wrap Dipper#diff in your codebase to avoid the four positional parameters
Assert at least one a-side operand before calling

When it happens

Trigger: dipper.diff(nil, sum_b, nil, nil) or an all-nil call; supplying only the b-side operands; permuting the four positional arguments (checksum_a, checksum_b, file_a, file_b) when calling from Ruby.

Common situations: Hand-written wrappers around Dipper#diff that misorder or omit the first-side arguments.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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