By default, most versions of the Windows API have a maximum path length of 260 characters. For more information, read the article Maximum Path Length Limitation (external link).
For smaller projects this limitation is generally not a problem. However, as project sizes increase, especially if the nesting level of sub-directories is large, this limit may be breached. Even if the project is below the limit, the location of the Perforce QAC project and its working directory requirements may cause the limit to be breached.
In Windows 10, version 1607 and later, Microsoft introduced a change to enable long paths (external link). This requires a change to the application manifest and a registry setting change on the target machine. Perforce have investigated enabling this feature within Perforce QAC, and found that after enabling long path support, integrations with 3rd party applications (including Microsoft tools) became impractical because of the lack of general support for long paths in the Windows eco system. Current builds of Perforce QAC do not have the longPathAware setting enabled in the manifest.
Until the Long Path support improves in the Windows eco system, we are limited to a maximum path length of 260 characters but there are several practical workarounds that can be employed to mitigate against the limit. To do this, you can use the following workarounds – some of which are more invasive than others:
- Relocate Source Code
- Relocate QAC Project
- Reduce QAC Project Source Code Structure Mirroring
- Use Windows Junctions (mklink /J)
- Use Windows Virtual Drives (subst)
Relocate Source Code
If your source code is located some way down the path, then consider moving it to a higher location. For example, if your project "ABS-Generic1" is located under D:\Users\neo\development\2025\auto\braking\ABS\Version1\, then consider moving it to : D:\ABS-Generic1
Relocate QAC Project
Often the Perforce QAC project is in the same location as the source code. However, this is not mandatory and the Perforce QAC project may be in another location, higher up the path. For example, if your source code is located at D:\Users\neo\development\2025\auto\braking\ABS\Version1\ABS-Generic1, then you could locate the Perforce QAC project at D:\QAC-ABS-Generic1.
- Create the Perforce QAC project:
- Set the SOURCE_ROOT to be local to the Perforce QAC project using the original location:
You can then sync/add source files to the project as usual.
Reduce QAC Project Source Code Structure Mirroring
During various operations, such as analysis and results viewing, Perforce QAC mirrors the directory structure of the source code, and this may cause the 260-character limit to be breached.
Analysis
If you analyze our sample program sample_cgicc_diff, the directory structure below the project will look something like:
├───prqa
│ ├───configs
│ │ └───Initial
│ │ ├───cip
│ │ ├───config
│ │ ├───logs
│ │ ├───output
│ │ │ └───_SOURCE_ROOT
│ │ │ └───src
│ │ │ ├───cgicc
│ │ │ ├───demo
│ │ │ └───diff
│ │ ├───reports
│ │ └───tmp
│ ├───unified
│ └───upgrade
└───src
├───cgicc
├───demo
└───diff
└───hdr
└───sysNotice the source code mirroring (prqa/configs/Initial/output/_SOURCE_CODE/src/…). For this trivial project the mirroring is not too bad, but for larger projects it can become significant and cause the project to breach the 260-character limit.
It is possible to reduce the mirroring by setting the environment variable QAC_MIN_OUTPUT_DIR (see Environment Variables) and re-analyze. The structure then becomes:
├───prqa
│ ├───configs
│ │ └───Initial
│ │ ├───cip
│ │ ├───config
│ │ ├───logs
│ │ ├───output
│ │ │ ├───cgicc-d1652cd25d31632c2d49
│ │ │ ├───demo-0d0e5514edb0b0e2dc6e
│ │ │ └───diff-3937df56d50e1e04f6dc
│ │ ├───reports
│ │ └───tmp
│ ├───unified
│ └───upgrade
└───src
├───cgicc
├───demo
└───diff
└───hdr
└───sysqacli view
The qacli view command (--medium XML | HTML) will also mirror the directory structure of the source code when creating the XML and HTML files. There are two possible mitigations:
- Use the
--output-pathoption to specify a location near the beginning of the path so it does not breach the 260-character limit. - Use the
--collate-outputoption to flatten the output directory structure (in a similar way toQAC_MIN_OUTPUT_DIR).
Use Windows Junctions (mklink /J)
Windows junctions (external link), also known as junction points, are a feature of the NTFS file system that allows you to create a symbolic link to a directory. This allows you to create a link to a deeply nested directory with a shorter path. For example:
mklink /J C:\QAC-kazlib “C:\LongPath\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890\kaz lib$”This creates a junction at C:\QAC-kazlib and you can use this location to sync, analyze, view etc a project as normal:
qacli analyze -cf -P C:\QAC-kazlib
Progress(Cleaning): ............................................... done
C:\TEMP\JN2\except.c:qac:0:1:4
C:\TEMP\JN2\hash.c:qac:0:2:3
C:\TEMP\JN2\list.c:qac:0:3:2
C:\TEMP\JN2\dict.c:qac:0:4:1
C:\TEMP\JN2\sfx.c:qac:0:5:0
Progress(File-based Analysis): ................................... done
5 successes and 0 failures.If you try to do this using the full path (as shown above in the mklink command) it will fail with an error such as:
C:\LongPath\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890\kaz lib$>qacli analyze -cf -P .
A filesystem exception has been encountered for the following path(s):
C:\LongPath\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890\kaz lib$\prqa\configs\Initial\config
System Error Code(206) : filename too long
See (external site) https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes for details.
Please check that your filesystem does not have permissions issues for the user data directory and/or your project directory:
C:\Users\sbainbridge\AppData\Local\Perforce\QAC-<version>
Windows users should ensure path lengths are less than 260 characters.
Please contact support if you cannot resolve this issue:
Website: www.perforce.com/
Support: www.perforce.com/support/request-supportUse Windows Virtual Drives (subst)
The subst command (external link) in Windows is a command-line utility that allows you to associate a path with a drive letter. This can be useful for creating virtual drives that point to specific directories, making it easier to access deeply nested folders without having to navigate through the entire path each time.
To associate the drive letter Z: with a deeply nested folder issue a command such as:
SUBST Z: "C:\LongPath\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890123456789012345678901234567890\123456789012345678901234567890\kaz lib$"You can then can use that new virtual drive: