{"record":{"id":"b556641240c10065","repo":"puppetlabs/puppet","slug":"failed-to-get-volume-information","errorCode":null,"errorMessage":"Failed to get volume information","messagePattern":"Failed to get volume information","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/security.rb","lineNumber":176,"sourceCode":"  def get_group(path)\n    return unless supports_acl?(path)\n\n    get_security_descriptor(path).group\n  end\n\n  FILE_PERSISTENT_ACLS = 0x00000008\n\n  def supports_acl?(path)\n    supported = false\n    root = Pathname.new(path).enum_for(:ascend).to_a.last.to_s\n    # 'A trailing backslash is required'\n    root = \"#{root}\\\\\" unless root =~ %r{[/\\\\]$}\n\n    FFI::MemoryPointer.new(:pointer, 1) do |flags_ptr|\n      if GetVolumeInformationW(wide_string(root), FFI::Pointer::NULL, 0,\n                               FFI::Pointer::NULL, FFI::Pointer::NULL,\n                               flags_ptr, FFI::Pointer::NULL, 0) == FFI::WIN32_FALSE\n        raise Puppet::Util::Windows::Error, _(\"Failed to get volume information\")\n      end\n\n      supported = flags_ptr.read_dword & FILE_PERSISTENT_ACLS == FILE_PERSISTENT_ACLS\n    end\n\n    supported\n  end\n\n  MASK_TO_MODE = {\n    FILE::FILE_GENERIC_READ => S_IROTH,\n    FILE::FILE_GENERIC_WRITE => S_IWOTH,\n    (FILE::FILE_GENERIC_EXECUTE & ~FILE::FILE_READ_ATTRIBUTES) => S_IXOTH\n  }\n\n  def get_aces_for_path_by_sid(path, sid)\n    get_security_descriptor(path).dacl.select { |ace| ace.sid == sid }\n  end\n","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/security.rb#L158-L194","documentation":"Raised by Security.supports_acl? (lib/puppet/util/windows/security.rb:176) when GetVolumeInformationW fails on the root of the given path. The method ascends the path to its volume root, appends a trailing backslash (required by the API), and queries the filesystem flags to test FILE_PERSISTENT_ACLS. Failure means the volume could not be queried at all: drive not ready (empty optical/removable drive), an unavailable network share, or a path whose root cannot be derived.","triggerScenarios":"Calling supports_acl? (directly or via Puppet file/ACL management) on an empty CD-ROM or unplugged removable drive (ERROR_NOT_READY 21); a UNC or mapped network path whose share is down (ERROR_BAD_NETPATH / path not found); a path supplied such that the derived root string is invalid.","commonSituations":"Agents managing files on removable or optical media; disconnected mapped drives at boot before the network is up; laptops with card readers; DFS shares temporarily unreachable.","solutions":["Gate on reachability before ACL work: File.exist?/Dir.exist? on the path, and net use for shares.","Rescue Puppet::Util::Windows::Error and treat an unqueryable volume as 'do not manage ACLs here' (return false), since transient media fail the query.","Order resources so network volumes are validated or retried after network facts are up.","Log e.code — 21 (ERROR_NOT_READY) and 53 (path/network not found) are the common transient codes."],"exampleFix":"# before\nsupports = Security.supports_acl?(path)\n\n# after — absent/transient volumes mean 'no ACL support'\nsupports = Dir.exist?(path) && begin\n  Security.supports_acl?(path)\nrescue Puppet::Util::Windows::Error\n  false\nend","handlingStrategy":"try-catch","validationCode":"raise ArgumentError, \"path not present: #{path}\" unless File.exist?(path)\nSecurity.supports_acl?(path)","typeGuard":null,"tryCatchPattern":"begin\n  ok = Security.supports_acl?(path)\nrescue Puppet::Util::Windows::Error => e\n  Puppet.debug \"volume query failed for #{path} (#{e.code})\"\n  ok = false # unqueryable volume — do not manage ACLs\nend","preventionTips":["Gate ACL management on File.exist? for removable and network paths","Retry after network-online on shares and mapped drives","Skip optical and removable media in file resources"],"tags":["windows","win32-api","filesystem","acl","volume","network-share","puppet"],"backgroundTag":"win32-volume-information-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}