puppetlabs/puppet · error · Puppet::ParseError

binary_file(): The given file '%{unresolved_path}' does not

Error message

binary_file(): The given file '%{unresolved_path}' does not exist

What it means

binary_file() reads a file as binary data during catalog compilation. It resolves the given path with Puppet::Parser::Files.find_file against the compiling environment; if resolution returns nothing, or the resolved path does not exist on the compiling node, it raises Puppet::ParseError. Relative paths resolve against module files/ directories, so a bare filename usually fails.

Source

Thrown at lib/puppet/functions/binary_file.rb:30

# An error is raised if the given file does not exists.
#
# To search for the existence of files, use the `find_file()` function.
#
# - since 4.8.0
#
# @since 4.8.0
#
Puppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunction) do
  dispatch :binary_file do
    scope_param
    param 'String', :path
  end

  def binary_file(scope, unresolved_path)
    path = Puppet::Parser::Files.find_file(unresolved_path, scope.compiler.environment)
    unless path && Puppet::FileSystem.exist?(path)
      # TRANSLATORS the string "binary_file()" should not be translated
      raise Puppet::ParseError, _("binary_file(): The given file '%{unresolved_path}' does not exist") % { unresolved_path: unresolved_path }
    end

    Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(Puppet::FileSystem.binread(path))
  end
end

View on GitHub (pinned to e227c27540)

Solutions

Use the module-qualified relative form: binary_file('mymodule/logo.png') maps to modules/mymodule/files/logo.png.
Or pass an absolute path that exists on the compiling node.
Verify on the compile node: ls modules/mymodule/files/logo.png (or the production environment path on the server).
Confirm the file is inside the module's files/ directory, not templates/ or files at the module root.

Example fix

# before: bare filename resolves nowhere
 $logo = binary_file('logo.png')

# after: module-qualified path resolves to modules/mymod/files/logo.png
 $logo = binary_file('mymod/logo.png')
 # or absolute, present on the compiling node:
 $logo = binary_file('/etc/puppetlabs/code/static/logo.png')

Defensive patterns

Strategy: validation

Validate before calling

# Before compiling, resolve the path the same way binary_file does
env = Puppet.lookup(:current_environment) rescue Puppet::Node::Environment.remote('production')
path = Puppet::Parser::Files.find_file('mymod/logo.png', env)
raise ArgumentError, 'binary_file source not found' unless path && Puppet::FileSystem.exist?(path)

Try / catch

begin
  site.compile
rescue Puppet::ParseError => e
  raise unless e.message =~ /binary_file\(\): .* does not exist/
  raise "missing binary_file source at manifest line #{e.line}: #{e.message}"
end

Prevention

Reference module files as '<module>/<path-under-files>'.
Place binary assets under modules/<name>/files/, not templates/ or the module root.
Remember compilation happens on the server: the file must exist there, not only on the target node.
Check filename case; resolution is case-sensitive.

When it happens

Trigger: binary_file('logo.png') in a manifest: the bare name matches nothing on the module path. Correct relative form is 'mymodule/logo.png', resolved to modules/mymodule/files/logo.png. An absolute path must already exist on the node that compiles the catalog (the server in master/agent mode).

Common situations: Forgetting the module prefix; running puppet apply on a node that lacks the module's files directory; master/agent confusion where the file exists on the target node but not on the compile server; case mismatches in filenames.

Related errors

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