{"record":{"id":"6afe456cd6cdde49","repo":"puppetlabs/puppet","slug":"cannot-symlink-on-this-platform-version","errorCode":null,"errorMessage":"Cannot symlink on this platform version","messagePattern":"Cannot symlink on this platform version","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/type/file/target.rb","lineNumber":37,"sourceCode":"      `links` attribute to `manage`.\"\n\n    newvalue(:notlink) do\n      # We do nothing if the value is absent\n      return :nochange\n    end\n\n    # Anything else, basically\n    newvalue(/./) do\n      @resource[:ensure] = :link unless @resource.should(:ensure)\n\n      # Only call mklink if ensure didn't call us in the first place.\n      currentensure = @resource.property(:ensure).retrieve\n      mklink if @resource.property(:ensure).safe_insync?(currentensure)\n    end\n\n    # Create our link.\n    def mklink\n      raise Puppet::Error, \"Cannot symlink on this platform version\" unless provider.feature?(:manages_symlinks)\n\n      target = should\n\n      # Clean up any existing objects.  The argument is just for logging,\n      # it doesn't determine what's removed.\n      @resource.remove_existing(target)\n\n      raise Puppet::Error, \"Could not remove existing file\" if Puppet::FileSystem.exist?(@resource[:path])\n\n      Puppet::Util::SUIDManager.asuser(@resource.asuser) do\n        mode = @resource.should(:mode)\n        if mode\n          Puppet::Util.withumask(0o00) do\n            Puppet::FileSystem.symlink(target, @resource[:path])\n          end\n        else\n          Puppet::FileSystem.symlink(target, @resource[:path])\n        end","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/type/file/target.rb#L19-L55","documentation":"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'.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["On Windows, run the agent elevated or grant SeCreateSymbolicLinkPrivilege to the service account (Developer Mode also permits non-admin symlinks).","Upgrade Puppet (and its bundled Ruby) to a version with working symlink support on the OS.","Where privilege cannot change, replace the link: a junction for directories, or ensure => file with source for content.","Pre-check capability before relying on links (see validation below)."],"exampleFix":"// before (fails when non-elevated on Windows)\nfile { 'C:/tmp/link':\n  ensure => link,\n  target => 'C:/tmp/real',\n}\n\n// after: run the agent elevated, or fall back to copying\nfile { 'C:/tmp/link':\n  ensure => file,\n  source => 'C:/tmp/real',\n}","handlingStrategy":"validation","validationCode":"# Ruby: gate ensure => link resources on provider capability\nif @resource[:ensure].to_s == 'link' && !@resource.provider.feature?(:manages_symlinks)\n  fail('symlinks unsupported on this platform/privilege — run elevated (Windows) or use a junction/copy')\nend","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Run Windows agents elevated or grant SeCreateSymbolicLinkPrivilege.","Enable Developer Mode on Windows 10+ for non-admin symlink creation.","Gate ensure => link resources on a capability fact for mixed fleets.","Keep Puppet/Ruby current so feature detection stays accurate."],"tags":["puppet","file","symlink","windows","privileges"],"backgroundTag":"unsupported-platform-operation","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}