{"record":{"id":"e44bb7eac8c73e0e","repo":"ansible/ansible","slug":"createsymboliclink-0-1-2-failed","errorCode":null,"errorMessage":"CreateSymbolicLink({0}, {1}, {2}) failed","messagePattern":"CreateSymbolicLink\\((.+?), (.+?), (.+?)\\) failed","errorType":"exception","errorClass":"LinkUtilWin32Exception","httpStatus":null,"severity":"error","filePath":"lib/ansible/module_utils/powershell/Ansible.ModuleUtils.LinkUtil.psm1","lineNumber":209,"sourceCode":"\n            if (!success)\n                throw new LinkUtilWin32Exception(String.Format(\"Failed to delete link at {0}\", linkPath));\n        }\n\n        public static void CreateLink(string linkPath, String linkTarget, LinkType linkType)\n        {\n            switch (linkType)\n            {\n                case LinkType.SymbolicLink:\n                    UInt32 linkFlags;\n                    FileAttributes attr = File.GetAttributes(linkTarget);\n                    if (attr.HasFlag(FileAttributes.Directory))\n                        linkFlags = SYMBOLIC_LINK_FLAG_DIRECTORY;\n                    else\n                        linkFlags = SYMBOLIC_LINK_FLAG_FILE;\n\n                    if (!CreateSymbolicLink(linkPath, linkTarget, linkFlags))\n                        throw new LinkUtilWin32Exception(String.Format(\"CreateSymbolicLink({0}, {1}, {2}) failed\", linkPath, linkTarget, linkFlags));\n                    break;\n                case LinkType.JunctionPoint:\n                    CreateJunctionPoint(linkPath, linkTarget);\n                    break;\n                case LinkType.HardLink:\n                    if (!CreateHardLink(linkPath, linkTarget, IntPtr.Zero))\n                        throw new LinkUtilWin32Exception(String.Format(\"CreateHardLink({0}, {1}) failed\", linkPath, linkTarget));\n                    break;\n            }\n        }\n\n        private static LinkInfo GetHardLinkInfo(string linkPath)\n        {\n            UInt32 maxPath = 260;\n            List<string> result = new List<string>();\n\n            StringBuilder sb = new StringBuilder((int)maxPath);\n            UInt32 stringLength = maxPath;","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/module_utils/powershell/Ansible.ModuleUtils.LinkUtil.psm1#L191-L227","documentation":"Thrown when CreateSymbolicLink returns false while creating a file or directory symlink. On modern Windows this is almost always ERROR_PRIVILEGE_NOT_HELD (1314): the account lacks SeCreateSymbolicLinkPrivilege, which by default only admins have (or regular users with Developer Mode enabled). The flag chosen (SYMBOLIC_LINK_FLAG_DIRECTORY vs FILE) comes from the target's attributes, so the target must also exist and be reachable.","triggerScenarios":"CreateLink(..., LinkType.SymbolicLink) as a non-admin without Developer Mode; target on a network share whose attributes cannot be read; long paths exceeding MAX_PATH without registry long-path support.","commonSituations":"Using ansible.windows.win_file with state=link via a non-admin account; Windows 10+ without Developer Mode; cross-OS behavior change in Python 3.8 that stopped auto-elevating symlink creation.","solutions":["Run the task as an administrator (become: yes with win_become) or grant SeCreateSymbolicLinkPrivilege to the account (secpol.msc > Local Policies > User Rights Assignment)","Enable Windows Developer Mode to allow non-admin symlink creation","Check the Win32 error code in the exception: 1314 = privilege, 2/3 = missing target, 206 = long path","Prefer LinkType.JunctionPoint when a directory link suffices — junctions need no special privilege"],"exampleFix":"- name: create symlink\n  ansible.windows.win_file:\n    path: C:\\link\n    state: link\n    # before: fails as non-admin with CreateSymbolicLink() failed (1314)\n# after:\n- name: create symlink (elevated)\n  ansible.windows.win_file:\n    path: C:\\link\n    state: link\n  become: yes\n  become_method: runas\n  become_user: Administrator","handlingStrategy":"validation","validationCode":"# validate privilege before attempting symlink creation\n$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)\n$devMode = (Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\AppModelUnlock' -ErrorAction SilentlyContinue).AllowDevelopmentWithoutDevLicense -eq 1\nif (-not ($isAdmin -or $devMode)) { throw 'symlink creation requires admin or Developer Mode' }","typeGuard":null,"tryCatchPattern":"try { [Ansible.ModuleUtils.LinkUtil]::CreateLink($link, $target, [LinkType]::SymbolicLink) } catch [LinkUtilWin32Exception] { if ($_.Exception.NativeErrorCode -eq 1314) { 'privilege missing: elevate or enable Developer Mode' } else { throw } }","preventionTips":["Run link tasks elevated or grant SeCreateSymbolicLinkPrivilege","Enable Developer Mode for non-admin workflows","Prefer junctions for directory links"],"tags":["windows","powershell","linkutil","symlink","privilege"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}