{"record":{"id":"53ed89b266e1c41d","repo":"puppetlabs/puppet","slug":"binary-file-the-given-file-unresolved-path","errorCode":null,"errorMessage":"binary_file(): The given file '%{unresolved_path}' does not exist","messagePattern":"binary_file\\(\\): The given file '%(.+?)' does not exist","errorType":"exception","errorClass":"Puppet::ParseError","httpStatus":null,"severity":"error","filePath":"lib/puppet/functions/binary_file.rb","lineNumber":30,"sourceCode":"# An error is raised if the given file does not exists.\n#\n# To search for the existence of files, use the `find_file()` function.\n#\n# - since 4.8.0\n#\n# @since 4.8.0\n#\nPuppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunction) do\n  dispatch :binary_file do\n    scope_param\n    param 'String', :path\n  end\n\n  def binary_file(scope, unresolved_path)\n    path = Puppet::Parser::Files.find_file(unresolved_path, scope.compiler.environment)\n    unless path && Puppet::FileSystem.exist?(path)\n      # TRANSLATORS the string \"binary_file()\" should not be translated\n      raise Puppet::ParseError, _(\"binary_file(): The given file '%{unresolved_path}' does not exist\") % { unresolved_path: unresolved_path }\n    end\n\n    Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(Puppet::FileSystem.binread(path))\n  end\nend\n","sourceCodeStart":12,"sourceCodeEnd":36,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/functions/binary_file.rb#L12-L36","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before: bare filename resolves nowhere\n $logo = binary_file('logo.png')\n\n# after: module-qualified path resolves to modules/mymod/files/logo.png\n $logo = binary_file('mymod/logo.png')\n # or absolute, present on the compiling node:\n $logo = binary_file('/etc/puppetlabs/code/static/logo.png')","handlingStrategy":"validation","validationCode":"# Before compiling, resolve the path the same way binary_file does\nenv = Puppet.lookup(:current_environment) rescue Puppet::Node::Environment.remote('production')\npath = Puppet::Parser::Files.find_file('mymod/logo.png', env)\nraise ArgumentError, 'binary_file source not found' unless path && Puppet::FileSystem.exist?(path)","typeGuard":null,"tryCatchPattern":"begin\n  site.compile\nrescue Puppet::ParseError => e\n  raise unless e.message =~ /binary_file\\(\\): .* does not exist/\n  raise \"missing binary_file source at manifest line #{e.line}: #{e.message}\"\nend","preventionTips":["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."],"tags":["puppet","functions","binary-file","file-not-found","compile-time"],"backgroundTag":"file-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}