{"record":{"id":"cbdaef3099fb3924","repo":"puppetlabs/puppet","slug":"failed-to-open-path","errorCode":null,"errorMessage":"Failed to open '%{path}'","messagePattern":"Failed to open '%(.+?)'","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/security.rb","lineNumber":525,"sourceCode":"\n    dacl\n  end\n\n  # Open an existing file with the specified access mode, and execute a\n  # block with the opened file HANDLE.\n  def open_file(path, access, &block)\n    handle = CreateFileW(\n      wide_string(path),\n      access,\n      FILE::FILE_SHARE_READ | FILE::FILE_SHARE_WRITE,\n      FFI::Pointer::NULL, # security_attributes\n      FILE::OPEN_EXISTING,\n      FILE::FILE_FLAG_OPEN_REPARSE_POINT | FILE::FILE_FLAG_BACKUP_SEMANTICS,\n      FFI::Pointer::NULL_HANDLE\n    ) # template\n\n    if handle == Puppet::Util::Windows::File::INVALID_HANDLE_VALUE\n      raise Puppet::Util::Windows::Error, _(\"Failed to open '%{path}'\") % { path: path }\n    end\n\n    begin\n      yield handle\n    ensure\n      FFI::WIN32.CloseHandle(handle) if handle\n    end\n\n    # handle has already had CloseHandle called against it, nothing to return\n    nil\n  end\n\n  # Execute a block with the specified privilege enabled\n  def with_privilege(privilege, &block)\n    set_privilege(privilege, true)\n    yield\n  ensure\n    set_privilege(privilege, false)","sourceCodeStart":507,"sourceCodeEnd":543,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/security.rb#L507-L543","documentation":"Raised by open_file when CreateFileW returns INVALID_HANDLE_VALUE. The file or directory is opened with OPEN_EXISTING plus FILE_FLAG_OPEN_REPARSE_POINT and FILE_FLAG_BACKUP_SEMANTICS, so the call fails outright when the path does not exist, access is denied, or the path cannot be opened in the requested mode. The appended Win32 message (via Puppet::Util::Windows::Error using FFI.errno) tells you which case it is, e.g. 'The system cannot find the file specified' or 'Access is denied'.","triggerScenarios":"get_security_descriptor or set_security_descriptor on a path that was deleted between catalog compile and run, a path the agent account cannot open (no READ_CONTROL for reads, no WRITE_DAC/WRITE_OWNER for writes), an invalid/overlong path, or a file exclusively locked with no share flags.","commonSituations":"Puppet managing a file that another process removes/recreates mid-run; running the agent as a limited user against system-owned files; paths longer than MAX_PATH; antivirus temporarily locking targets.","solutions":["Check the appended Win32 text / e.code: 2 = file not found, 5 = access denied, 32 = sharing violation","Verify the path exists at run time (File.exist?) before touching security on it","Run the agent elevated (Administrator) or grant the agent account READ_CONTROL/WRITE_DAC on the target","For long paths, use an absolute path with the \\\\?\\\\ prefix or shorten the directory tree"],"exampleFix":"// before\nPuppet::Util::Windows::Security.get_security_descriptor(path)\n\n# after\nunless File.exist?(path)\n  raise Puppet::Error, \"Cannot manage ACL: #{path} does not exist\"\nend\nPuppet::Util::Windows::Security.get_security_descriptor(path)","handlingStrategy":"validation","validationCode":"raise Puppet::Error, \"#{path} does not exist\" unless File.exist?(path)\n# ensure the agent can open it for security reads\naccessible = File.readable?(path) rescue false","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Util::Windows::Security.get_security_descriptor(path)\nrescue Puppet::Util::Windows::Error => e\n  case e.code\n  when 2 then Puppet.err \"#{path} vanished mid-run\"\n  when 5 then Puppet.err \"#{path}: no access; run agent elevated\"\n  when 32 then Puppet.err \"#{path}: sharing violation; retry later\"\n  end\n  raise\nend","preventionTips":["Check File.exist? immediately before touching security, not at compile time","Run the agent elevated when managing system-owned paths","Handle code 2 (not found) and 5 (access denied) distinctly; they need different fixes"],"tags":["windows","file-access","security","win32","createfile"],"backgroundTag":"windows-file-open-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}