puppetlabs/puppet · error · Puppet::Error

Cannot symlink on this platform version

Error message

Cannot symlink on this platform version

What it means

target#mklink creates the symlink for `ensure => link` resources, but first asserts that the file provider advertises the :manages_symlinks feature. On platform/privilege combinations that cannot create symlinks — most notably Windows processes lacking SeCreateSymbolicLinkPrivilege — it raises 'Cannot symlink on this platform version'.

Source

Thrown at lib/puppet/type/file/target.rb:37

      `links` attribute to `manage`."

    newvalue(:notlink) do
      # We do nothing if the value is absent
      return :nochange
    end

    # Anything else, basically
    newvalue(/./) do
      @resource[:ensure] = :link unless @resource.should(:ensure)

      # Only call mklink if ensure didn't call us in the first place.
      currentensure = @resource.property(:ensure).retrieve
      mklink if @resource.property(:ensure).safe_insync?(currentensure)
    end

    # Create our link.
    def mklink
      raise Puppet::Error, "Cannot symlink on this platform version" unless provider.feature?(:manages_symlinks)

      target = should

      # Clean up any existing objects.  The argument is just for logging,
      # it doesn't determine what's removed.
      @resource.remove_existing(target)

      raise Puppet::Error, "Could not remove existing file" if Puppet::FileSystem.exist?(@resource[:path])

      Puppet::Util::SUIDManager.asuser(@resource.asuser) do
        mode = @resource.should(:mode)
        if mode
          Puppet::Util.withumask(0o00) do
            Puppet::FileSystem.symlink(target, @resource[:path])
          end
        else
          Puppet::FileSystem.symlink(target, @resource[:path])
        end

View on GitHub (pinned to e227c27540)

Solutions

1. On Windows, run the agent elevated or grant SeCreateSymbolicLinkPrivilege to the service account (Developer Mode also permits non-admin symlinks).
2. Upgrade Puppet (and its bundled Ruby) to a version with working symlink support on the OS.
3. Where privilege cannot change, replace the link: a junction for directories, or ensure => file with source for content.
4. Pre-check capability before relying on links (see validation below).

Example fix

// before (fails when non-elevated on Windows)
file { 'C:/tmp/link':
  ensure => link,
  target => 'C:/tmp/real',
}

// after: run the agent elevated, or fall back to copying
file { 'C:/tmp/link':
  ensure => file,
  source => 'C:/tmp/real',
}

# Ruby: gate ensure => link resources on provider capability
if @resource[:ensure].to_s == 'link' && !@resource.provider.feature?(:manages_symlinks)
  fail('symlinks unsupported on this platform/privilege — run elevated (Windows) or use a junction/copy')
end

rescue Puppet::Error on /Cannot symlink on this platform version/ — the condition is permanent for that platform/privilege, so switch strategy (junction, copy, ensure => file) instead of retrying.

When it happens

Trigger: `file { 'C:/tmp/link': ensure => link, target => 'C:/tmp/real' }` on Windows where the agent runs non-elevated without Developer Mode; old Ruby/Puppet versions whose Windows provider omitted the feature; exotic platforms whose provider does not declare manages_symlinks.

Common situations: Windows agents running as a non-admin service without the symlink privilege; hardened boxes where local policy strips SeCreateSymbolicLinkPrivilege; Puppet/Ruby upgrades changing feature detection; porting POSIX manifests to Windows.

Related errors

• Could not remove existing file
• CreateSymbolicLink(#{symlink}, #{target}, #{flags.to_s(8)})
• Retrieving NFS reparse point data is unsupported
• DeviceIoControl(#{handle}, FSCTL_GET_REPARSE_POINT) returned
• Calling `#{method_name}` returned 'Win32 Error Code 0x%08X'.

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/6afe456cd6cdde49. Report an issue: GitHub.