Skip to main content
Last updated on Oct 12, 2026 This feature is only available in Incredibuild’s Enterprise and Business Plans. Build Cache records the paths of the files that each task reads and writes. If the same code is built from different folders, those paths differ, and a machine looking up a task can miss an entry that another machine stored for identical work. Common causes:
  • Each CI runner builds in a different workspace folder.
  • Visual Studio or a Windows SDK is installed in a different location on each machine.
  • A per-user package cache, such as Conan or NuGet, lives under each user’s profile.
To get cache hits in these cases, Build Cache normalizes paths before it stores or looks up a task. Known paths tell Build Cache which folders hold the same content on every machine even when their location differs.

​
How Paths Are Normalized

Build Cache normalizes each path in one of the following ways:
  1. Known path alias. If a path is under a configured known path, that prefix is replaced by the alias, written as @ALIAS. For example, with a known path CONAN set to C:\Users\jdoe\.conan2, the file C:\Users\jdoe\.conan2\p\zlib\include\zlib.h is recorded as @CONAN\p\zlib\include\zlib.h. A machine where the Conan home is D:\conan records the same file as the same entry.
  2. Relative to the working directory. Any other path is made relative to the compiler’s working directory, when both are under the same top-level folder on the same drive. This is why the project root can be C:\Project on one Initiator and D:\Project on another. Paths on another drive, or outside that top-level folder, stay absolute—these are the paths that need a known path.
  3. MSVC debug paths. For MSVC compilations, the msvcPreferRelativePaths setting, which is on by default, also adds /d1trimfile to the compilation. This trims the working directory from the paths that the compiler embeds in its output.

​
Automatic Known Paths

Visual Studio installations and Windows SDKs detected on the machine are added as known paths automatically. You do not need to configure them, even if they are installed in different locations on different machines. Other folders, such as CI workspaces or package caches outside the defaults, need to be configured in the configuration file or on the command line.

​
Configure Known Paths in the Configuration File

From version 10.24, add a knownPaths section to the following file on each Initiator. Create the file if it does not exist:
Each entry maps an alias to a folder on that machine:
If the file already contains other settings, leave them in place and add knownPaths alongside them. Ensure that:
  1. The alias is identical on every machine. The path is the folder on that specific machine and can differ between machines.
  2. Each alias maps to one path, and each path maps to one alias. Within one file, an alias cannot map to two paths, and a path cannot map to two aliases.
  3. Backslashes are doubled, because the file is JSON.
Aliases and paths are not case-sensitive. Paths can contain environment variables, such as %USERPROFILE% or %CONAN_HOME%. A path that does not exist yet is accepted.

​
How the File Is Merged with the Defaults

Incredibuild ships default known paths in <install folder>\resources\buildcache_client_config.json, such as:
Do not edit the file in the installation folder. Setup overwrites it when Incredibuild is installed or upgraded. Make your changes in the %PROGRAMDATA% file instead.
The entries in the %PROGRAMDATA% file are merged with the defaults:
  • You only need to list the entries you are adding or changing. The defaults stay in effect.
  • An entry with the same alias as a default overrides that default.
  • An entry set to "" turns that default off. For example, "nuGet": "".

​
Add Known Paths on the Command Line

You can also add known paths for a single build using the BuildConsole /AddKnownPath option:
  • Repeat the option to add more than one known path.
  • The alias is the text before the first :. The rest is the path, so a path with a drive letter works as expected, for example /AddKnownPath=SdkRoot:C:\dev\SDK.
  • If the path is quoted and ends with a backslash, end it with \\", for example /AddKnownPath=VS:"C:\Program Files\Microsoft Visual Studio\\".
The same rules apply as in the configuration file: use the same alias on every machine. For the full list of options, see BuildConsole for Visual Studio.

​
Changing Known Paths

When you add, change, or remove a known path, the cache entries stored under the old paths no longer match. Expect a lower hit rate on the next build, while Build Cache repopulates the cache with entries under the new paths. Run one build on a machine that writes to the cache to repopulate it.

​
Common Recipes

​
Check That It Works

Look in the Build Cache client log, BuildCacheClient.log, under the Logs\BuildCache folder of the Incredibuild installation folder. Search for these messages:
  • added known path: the known path was registered.
  • does not exist yet: the known path was registered, but the folder did not exist on this machine when the build started. This is harmless if the folder is created later, but check for a typo if you expected it to exist.
Some of these messages are only written at higher logging levels. If you do not see them, raise the Agent logging level and run the build again. To find tasks that still miss the cache, use the Build Cache hit/miss report.