2 +name: windows-filename-guidance
3 +description: "Use for Windows filename rules and failures involving reserved DOS device names such as NUL, invalid or trailing characters, inaccessible cross-platform names, long paths, or files that Windows cannot inspect, rename, or delete normally."
4 +compatibility: "Windows with cmd.exe"
7 +#
Windows Filename Guidance 11 +Separate three layers:
13 +1. the filesystem's on-disk rules
14 +2. Windows path namespace and normalization
15 +3. the application's API and path handling
17 +A name can exist on NTFS yet be unreachable through an ordinary Win32 path.
18 +This commonly happens when another operating system, namespace, share, or tool
19 +created it. It does not by itself prove corruption or bad permissions.
21 +##
Normal Windows Names 23 +For portable Windows names:
25 +- Do not use control characters U+0000 through U+001F or `<>:"/\|?*`.
26 +- Do not end a component with a space or period; Win32 normally strips them.
27 +- Do not use `.` or `..` as components.
28 +- Do not use `CON`, `PRN`, `AUX`, `NUL`, `COM1` through `COM9`, or `LPT1`
29 + through `LPT9`, regardless of case. An extension does not help: `NUL.txt`
30 + still resolves as `NUL`.
31 +- Treat `:` as the drive/alternate-data-stream separator, not filename text.
32 +- Assume case-insensitive lookup even though case is preserved.
33 +- Keep each component within the filesystem limit. Path-length support depends
34 + on the filesystem, API, application, and whether long paths are enabled.
36 +Use these rules when generating archives, repositories, build output, or shared
37 +files intended for Windows.
41 +1. Get the exact absolute path, error text, filesystem, and whether the target
42 + is a file or directory.
43 +2. Enumerate the parent rather than probing the suspect name directly:
46 + cmd.exe /d /c dir /a /x "C:\absolute\parent"
49 +3. Classify the failure:
50 + - reserved device name
51 + - trailing space/period or other Win32-invalid name
52 + - path too long for the current tool
54 + - ACL/ownership denial
55 + - filesystem corruption supported by disk or event-log errors
56 +4. Prefer the same namespace, share, or program that created the entry when it
57 + can safely rename or remove it.
59 +Never use `Test-Path NUL` or `if exist NUL` to prove a file exists; those can
64 +For an existing local entry that ordinary Win32 normalization cannot address,
65 +use an exact absolute extended path:
71 +For UNC paths, convert `\\server\share\path` to:
74 +\\?\UNC\server\share\path
77 +The `\\?\` prefix bypasses ordinary Win32 parsing; it does not bypass the
78 +filesystem's rules, ACLs, locks, or corruption. Do not combine it with a
81 +##
Delete Problem Entries 83 +Show the exact target and obtain explicit confirmation first. Reject wildcards,
84 +relative paths, drive/share roots, and ambiguous targets.
89 +cmd.exe /d /c del "\\?\C:\absolute\path\NUL"
92 +Read-only file, only after reporting why:
95 +cmd.exe /d /c del /f "\\?\C:\absolute\path\NUL"
101 +cmd.exe /d /c rd "\\?\C:\absolute\path\NUL"
104 +Nonempty directory: enumerate its contents and obtain separate recursive-delete
105 +confirmation before running:
108 +cmd.exe /d /c rd /s /q "\\?\C:\absolute\path\NUL"
111 +Preserve exact spelling, extension, spaces, and periods. Enumerate the parent
112 +again; report success only when the literal entry is absent.
114 +If the extended path still fails, use `dir /a /x` on the parent. Verify the 8.3
115 +short name maps to the exact target before proposing deletion through that name.
119 +- Open handle: identify and close the owning process before retrying.
120 +- ACL denial: inspect ownership and permissions; request elevation or ownership
121 + changes only when confirmed necessary.
122 +- Deep path: use an extended path, shorten a parent, map a deeper drive/share,
123 + or use a tool that supports the full path.
124 +- Corruption: run filesystem repair only when independent evidence supports it;
125 + an odd filename alone is insufficient.
126 +- Missing parent entry: stop. A successful reference to `NUL` alone is the
127 + null device, not evidence of a file.
131 +- [Super User: removing a file named NUL](https://superuser.com/questions/282194/how-do-i-remove-a-file-named-nul-on-windows)
132 +- [Microsoft KB 320081: undeletable NTFS entries](https://learn.microsoft.com/en-us/troubleshoot/windows-server/backup-and-storage/cannot-delete-file-folder-on-ntfs-file-system)
133 +- [Microsoft: Naming Files, Paths, and Namespaces](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file)
134 +- [Wikipedia: filename limitations](https://en.wikipedia.org/wiki/Filename#Comparison_of_filename_limitations)