{"record":{"id":"e326cedad2cf4774","repo":"puppetlabs/puppet","slug":"createfile-file-name-desired-access-to-s-8","errorCode":null,"errorMessage":"CreateFile(#{file_name}, #{desired_access.to_s(8)}, #{share_mode.to_s(8)}, #{security_attributes}, #{creation_disposition.to_s(8)}, #{flags_and_attributes.to_s(8)}, #{template_file_handle})","messagePattern":"CreateFile\\(#(.+?), #(.+?), #(.+?), #(.+?), #(.+?), #(.+?), #(.+?)\\)","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/file.rb","lineNumber":137,"sourceCode":"    success = SetFileAttributesW(wide_string(path), flags) != FFI::WIN32_FALSE\n    raise Puppet::Util::Windows::Error, _(\"Failed to set file attributes\") unless success\n\n    success\n  end\n  module_function :set_attributes\n\n  # define INVALID_HANDLE_VALUE ((HANDLE)(LONG_PTR)-1)\n  INVALID_HANDLE_VALUE = FFI::Pointer.new(-1).address\n  def self.create_file(file_name, desired_access, share_mode, security_attributes,\n                       creation_disposition, flags_and_attributes, template_file_handle)\n\n    result = CreateFileW(wide_string(file_name.to_s),\n                         desired_access, share_mode, security_attributes, creation_disposition,\n                         flags_and_attributes, template_file_handle)\n\n    return result unless result == INVALID_HANDLE_VALUE\n\n    raise Puppet::Util::Windows::Error, \"CreateFile(#{file_name}, #{desired_access.to_s(8)}, #{share_mode.to_s(8)}, \" \\\n                                        \"#{security_attributes}, #{creation_disposition.to_s(8)}, \" \\\n                                        \"#{flags_and_attributes.to_s(8)}, #{template_file_handle})\"\n  end\n\n  def self.get_reparse_point_data(handle, &block)\n    # must be multiple of 1024, min 10240\n    FFI::MemoryPointer.new(MAXIMUM_REPARSE_DATA_BUFFER_SIZE) do |reparse_data_buffer_ptr|\n      device_io_control(handle, FSCTL_GET_REPARSE_POINT, nil, reparse_data_buffer_ptr)\n\n      reparse_tag = reparse_data_buffer_ptr.read_win32_ulong\n      buffer_type = case reparse_tag\n                    when IO_REPARSE_TAG_SYMLINK\n                      SYMLINK_REPARSE_DATA_BUFFER\n                    when IO_REPARSE_TAG_MOUNT_POINT\n                      MOUNT_POINT_REPARSE_DATA_BUFFER\n                    when IO_REPARSE_TAG_NFS\n                      raise Puppet::Util::Windows::Error, \"Retrieving NFS reparse point data is unsupported\"\n                    else","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/file.rb#L119-L155","documentation":"Puppet::Util::Windows::File.create_file wraps CreateFileW and raises Puppet::Util::Windows::Error when the returned handle equals INVALID_HANDLE_VALUE. The message dumps every argument (access, share mode, security attributes, disposition, flags - most in octal) so you can reproduce the exact open. e.code carries the Win32 reason: not-found, access denied, sharing violation, or invalid parameter combination.","triggerScenarios":"Opening a nonexistent path (2/3) with an OPEN_EXISTING-style disposition; requesting GENERIC_WRITE on admin-owned files unelevated (5); opening a file another process holds without a compatible share_mode (32); passing mutually exclusive creation_disposition/flags_and_attributes; opening a symlink without FILE_FLAG_OPEN_REPARSE_POINT; paths beyond MAX_PATH without long-path enablement.","commonSituations":"Puppet opening files for content replacement under Program Files as a filtered token; reparse-point inspection (this wrapper feeds get_reparse_point_data) where the link was removed between stat and open; backup software holding exclusive locks; long nested module paths exceeding 260 characters.","solutions":["Decode e.code first: 2/3 path, 5 rights, 32 lock, 87 bad flag/disposition combo","Ensure the disposition matches reality (CREATE_ALWAYS vs OPEN_EXISTING)","Match share_mode with how other holders opened the file, or wait for the lock","Run elevated for system files; enable long-path support (gpedit/registry LongPathsEnabled) for deep paths"],"exampleFix":"// before\nhandle = Puppet::Util::Windows::File.create_file(path, GENERIC_READ, 0, nil, OPEN_EXISTING, 0, 0)\n\n// after\nbegin\n  handle = Puppet::Util::Windows::File.create_file(path, GENERIC_READ, FILE_SHARE_READ, nil, OPEN_EXISTING, 0, 0)\nrescue Puppet::Util::Windows::Error => e\n  raise Puppet::Error, \"cannot open #{path}: win32 code #{e.code}\" \nend","handlingStrategy":"try-catch","validationCode":"raise ArgumentError, 'path missing' unless File.exist?(path)\nshare_mode ||= Puppet::FFI::Windows::Constants::FILE_SHARE_READ | Puppet::FFI::Windows::Constants::FILE_SHARE_WRITE","typeGuard":null,"tryCatchPattern":"begin\n  handle = Puppet::Util::Windows::File.create_file(path, desired_access, share_mode, security_attributes,\n                                                 creation_disposition, flags_and_attributes, template_file_handle)\nrescue Puppet::Util::Windows::Error => e\n  raise \"#{path}: not found\" if [2, 3].include?(e.code)\n  raise \"#{path}: access denied\" if e.code == 5\n  raise \"#{path}: locked by another process\" if e.code == 32\n  raise\nend","preventionTips":["Open with FILE_FLAG_OPEN_REPARSE_POINT when inspecting symlinks","Include FILE_SHARE_READ|FILE_SHARE_WRITE in share_mode unless exclusivity is required","Enable Windows long-path support for deep directory trees"],"tags":["windows","file-system","win32-api","ffi","file-handle","puppet"],"backgroundTag":"win32-file-open-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}