{"record":{"id":"06236a814a423007","repo":"puppetlabs/puppet","slug":"failed-to-initialize-acl","errorCode":null,"errorMessage":"Failed to initialize ACL","messagePattern":"Failed to initialize ACL","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/security.rb","lineNumber":645,"sourceCode":"\n    sd\n  end\n\n  def get_max_generic_acl_size(ace_count)\n    # https://msdn.microsoft.com/en-us/library/windows/desktop/aa378853(v=vs.85).aspx\n    # To calculate the initial size of an ACL, add the following together, and then align the result to the nearest DWORD:\n    # * Size of the ACL structure.\n    # * Size of each ACE structure that the ACL is to contain minus the SidStart member (DWORD) of the ACE.\n    # * Length of the SID that each ACE is to contain.\n    ACL.size + ace_count * MAXIMUM_GENERIC_ACE_SIZE\n  end\n\n  # setting DACL requires both READ_CONTROL and WRITE_DACL access rights,\n  # and their respective privileges, SE_BACKUP_NAME and SE_RESTORE_NAME.\n  def set_security_descriptor(path, sd)\n    FFI::MemoryPointer.new(:byte, get_max_generic_acl_size(sd.dacl.count)) do |acl_ptr|\n      if InitializeAcl(acl_ptr, acl_ptr.size, ACL_REVISION) == FFI::WIN32_FALSE\n        raise Puppet::Util::Windows::Error, _(\"Failed to initialize ACL\")\n      end\n\n      if IsValidAcl(acl_ptr) == FFI::WIN32_FALSE\n        raise Puppet::Util::Windows::Error, _(\"Invalid DACL\")\n      end\n\n      with_privilege(SE_BACKUP_NAME) do\n        with_privilege(SE_RESTORE_NAME) do\n          open_file(path, READ_CONTROL | WRITE_DAC | WRITE_OWNER) do |handle|\n            Puppet::Util::Windows::SID.string_to_sid_ptr(sd.owner) do |owner_sid_ptr|\n              Puppet::Util::Windows::SID.string_to_sid_ptr(sd.group) do |group_sid_ptr|\n                sd.dacl.each do |ace|\n                  case ace.type\n                  when Puppet::Util::Windows::AccessControlEntry::ACCESS_ALLOWED_ACE_TYPE\n                    # puts \"ace: allow, sid #{Puppet::Util::Windows::SID.sid_to_name(ace.sid)}, mask 0x#{ace.mask.to_s(16)}\"\n                    add_access_allowed_ace(acl_ptr, ace.mask, ace.sid, ace.flags)\n                  when Puppet::Util::Windows::AccessControlEntry::ACCESS_DENIED_ACE_TYPE\n                    # puts \"ace: deny, sid #{Puppet::Util::Windows::SID.sid_to_name(ace.sid)}, mask 0x#{ace.mask.to_s(16)}\"","sourceCodeStart":627,"sourceCodeEnd":663,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/security.rb#L627-L663","documentation":"Raised by set_security_descriptor when InitializeAcl fails on the freshly allocated ACL buffer sized by get_max_generic_acl_size. InitializeAcl only fails when the buffer is too small for the ACL header (below ~8 bytes, e.g. a degenerate allocation) or the revision is wrong, so in this code path it signals an allocation/sizing problem rather than anything about the target file.","triggerScenarios":"set_security_descriptor where get_max_generic_acl_size(sd.dacl.count) computes a size smaller than the minimum ACL header (only conceivable with a broken ace_count) or FFI memory allocation returned a bad buffer; ACL_REVISION mismatch on the running Windows version.","commonSituations":"Almost never seen in practice; occasionally reported after memory pressure or FFI binding issues on unusual Ruby builds (e.g. 32-bit/64-bit struct layout mismatches).","solutions":["Check the appended Win32 text / e.code for the concrete reason","Verify the DACL being applied has a sane, non-negative ACE count","Reproduce with the same Ruby/FFI versions; mismatched ffi gem struct layouts can corrupt sizes","Reduce ACL size applied to the resource and retry"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Util::Windows::Security.set_security_descriptor(path, sd)\nrescue Puppet::Util::Windows::Error => e\n  raise unless e.message.include?('Failed to initialize ACL')\n  raise Puppet::Error, \"ACL init failed (code #{e.code}); check Ruby/ffi compatibility and ACE count #{sd.dacl.count}\"\nend","preventionTips":["Keep Puppet and the ffi gem versions aligned; struct layout drift shows up exactly here","Sanity-check the ACE count of descriptors you construct before applying"],"tags":["windows","acl","security","win32","ffi"],"backgroundTag":"windows-acl-initialization-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}