{"record":{"id":"c721700c037a10b7","repo":"puppetlabs/puppet","slug":"this-version-of-windows-does-not-support-symlinks","errorCode":null,"errorMessage":"This version of Windows does not support symlinks.  Windows Vista / 2008 or higher is required.","messagePattern":"This version of Windows does not support symlinks\\.  Windows Vista / 2008 or higher is required\\.","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/file_system/windows.rb","lineNumber":217,"sourceCode":"      Puppet::Util::Windows::SID::BuiltinAdministrators,\n      current_sid\n    ].uniq.map do |sid|\n      dacl.allow(sid, FULL_CONTROL)\n    end\n    dacl\n  end\n\n  def get_dacl_from_file(path)\n    sd = Puppet::Util::Windows::Security.get_security_descriptor(path_string(path))\n    sd.dacl\n  rescue Puppet::Util::Windows::Error => e\n    raise e unless e.code == FILE_NOT_FOUND\n  end\n\n  def raise_if_symlinks_unsupported\n    unless Puppet.features.manages_symlinks?\n      msg = _(\"This version of Windows does not support symlinks.  Windows Vista / 2008 or higher is required.\")\n      raise Puppet::Util::Windows::Error, msg\n    end\n\n    unless Puppet::Util::Windows::Process.process_privilege_symlink?\n      Puppet.warning _(\"The current user does not have the necessary permission to manage symlinks.\")\n    end\n  end\nend\n","sourceCodeStart":199,"sourceCodeEnd":225,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/file_system/windows.rb#L199-L225","documentation":"Before any symlink operation, the Windows file-system layer calls raise_if_symlinks_unsupported: if Puppet.features.manages_symlinks? is false (the Puppet runtime lacks symlink support, classically Windows older than Vista/2008), it raises Puppet::Util::Windows::Error. Separately, if the user merely lacks the symlink privilege it only warns, so the raise is specifically about OS/runtime capability.","triggerScenarios":"Managing `ensure => link` file resources (or links => manage during recursive file serving) on a Windows host whose Ruby/Puppet build cannot create symlinks; running modern Puppet on legacy Windows (XP/2003) or a stripped runtime without symlink support.","commonSituations":"Legacy Windows fleets; unusual Ruby builds where the symlink functions are unavailable; modules assuming POSIX symlink semantics deployed to old Windows nodes.","solutions":["Run the agent on Windows Vista/Server 2008 or newer with a Puppet build that supports symlinks","If upgrading the OS is not possible, avoid link resources on those nodes: use directory junctions via an exec, copy the target instead of linking, or condition resources on osfamily","Note the separate 'current user does not have the necessary permission' message is only a warning (elevation/SeCreateSymbolicLinkPrivilege fixes it), not this error"],"exampleFix":"# before (manifest)\nfile { 'C:/opt/current': ensure => link, target => 'C:/opt/rel-1.2.3' }\n\n# after (manifest, legacy Windows)\nif $facts['os']['family'] == 'windows' and versioncmp($facts['os']['release']['major'], '6.0') < 0 {\n  file { 'C:/opt/current': ensure => directory, source => 'puppet:///modules/app/rel-1.2.3', recurse => true }\n} else {\n  file { 'C:/opt/current': ensure => link, target => 'C:/opt/rel-1.2.3' }\n}","handlingStrategy":"validation","validationCode":"def symlink_capable?\n  Puppet.features.manages_symlinks? && Puppet::Util::Windows::Process.process_privilege_symlink?\nend\n\nuse_junction = Gem.win_platform? && !symlink_capable?","typeGuard":"# Feature guard usable in manifests\n# $facts['os']['family'] == 'windows' and versioncmp($facts['os']['release']['major'], '6.0') >= 0","tryCatchPattern":"begin\n  Puppet::FileSystem.link(target, link_path)\nrescue Puppet::Util::Windows::Error => e\n  raise unless e.message.include?('does not support symlinks')\n  fallback_to_copy_or_junction\nend","preventionTips":["Gate link resources on OS capability facts, not assumptions","Run agents as admin (or grant SeCreateSymbolicLinkPrivilege) where links are required","Prefer junctions/directory copies on legacy Windows nodes"],"tags":["puppet","windows","symlinks","platform-support"],"backgroundTag":"unsupported-platform-feature","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}