ansible/ansible · error · LinkUtilWin32Exception

CreateSymbolicLink({0}, {1}, {2}) failed

Error message

CreateSymbolicLink({0}, {1}, {2}) failed

What it means

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.

Source

Thrown at lib/ansible/module_utils/powershell/Ansible.ModuleUtils.LinkUtil.psm1:209

            if (!success)
                throw new LinkUtilWin32Exception(String.Format("Failed to delete link at {0}", linkPath));
        }

        public static void CreateLink(string linkPath, String linkTarget, LinkType linkType)
        {
            switch (linkType)
            {
                case LinkType.SymbolicLink:
                    UInt32 linkFlags;
                    FileAttributes attr = File.GetAttributes(linkTarget);
                    if (attr.HasFlag(FileAttributes.Directory))
                        linkFlags = SYMBOLIC_LINK_FLAG_DIRECTORY;
                    else
                        linkFlags = SYMBOLIC_LINK_FLAG_FILE;

                    if (!CreateSymbolicLink(linkPath, linkTarget, linkFlags))
                        throw new LinkUtilWin32Exception(String.Format("CreateSymbolicLink({0}, {1}, {2}) failed", linkPath, linkTarget, linkFlags));
                    break;
                case LinkType.JunctionPoint:
                    CreateJunctionPoint(linkPath, linkTarget);
                    break;
                case LinkType.HardLink:
                    if (!CreateHardLink(linkPath, linkTarget, IntPtr.Zero))
                        throw new LinkUtilWin32Exception(String.Format("CreateHardLink({0}, {1}) failed", linkPath, linkTarget));
                    break;
            }
        }

        private static LinkInfo GetHardLinkInfo(string linkPath)
        {
            UInt32 maxPath = 260;
            List<string> result = new List<string>();

            StringBuilder sb = new StringBuilder((int)maxPath);
            UInt32 stringLength = maxPath;

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Run the task as an administrator (become: yes with win_become) or grant SeCreateSymbolicLinkPrivilege to the account (secpol.msc > Local Policies > User Rights Assignment)
2. Enable Windows Developer Mode to allow non-admin symlink creation
3. Check the Win32 error code in the exception: 1314 = privilege, 2/3 = missing target, 206 = long path
4. Prefer LinkType.JunctionPoint when a directory link suffices — junctions need no special privilege

Example fix

- name: create symlink
  ansible.windows.win_file:
    path: C:\link
    state: link
    # before: fails as non-admin with CreateSymbolicLink() failed (1314)
# after:
- name: create symlink (elevated)
  ansible.windows.win_file:
    path: C:\link
    state: link
  become: yes
  become_method: runas
  become_user: Administrator

# validate privilege before attempting symlink creation
$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
$devMode = (Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -ErrorAction SilentlyContinue).AllowDevelopmentWithoutDevLicense -eq 1
if (-not ($isAdmin -or $devMode)) { throw 'symlink creation requires admin or Developer Mode' }

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 } }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to delete link at {0}
• CreateHardLink({0}, {1}) failed
• GetVolumePathName() failed
• CreateFile({0}) failed
• DeviceIoControl() failed for file at {0}

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/e44bb7eac8c73e0e. Report an issue: GitHub.