Distributed Compilation Troubleshooting

If you've followed the setup instructions and still can't seem to make it work, this guide is for you.

Try each each section in order.

1. Confirm FASTBUILD_BROKERAGE_PATH is Set

Make sure the brokerage path environment variable (FASTBUILD_BROKERAGE_PATH) is set on the Client (machine initiating the build) and the Server(s) (machines running the FBuildWorker).

You may need to reboot/logout to propagate new Environment Variables.

2. Confirm Brokerage Read/Write Access

Make sure your brokerage path can be accessed from both the Client and Server(s). Viewing the path through Windows Explorer/Finder/etc is usually sufficient to ensure the path is correct and permissions don't prevent read access.

Try creating a file in this directory to ensure write permissions are granted.

3. Verify the brokerage structure

With at least one worker running, a directory strucure should be created in your brokerage path:

If this folder structure is missing, check for write permissions.

1. Ensure Worker(s) are Available

Check the UI of your worker(s) to ensure they show some CPUs as "Idle" (and therefore available for use).

It your worker PC has other applications constantly consuming non-trivial amounts of CPU time (>10%), the worker may never become available.

To force a worker to be available, ignoring local CPU usage of other processes, you can set the "Current Mode" to "Work For Others Always":

2. Check Worker is Available in Brokerage

When a worker is available, it will create a token in the brokerage structure:

If this token is missing, check for write permissions.

1. Ensure Distribution is Activated

Distributed compilation must be activated on the command line with -dist.

1. Ensure Client is finding Workers

When the build starts, you should see some output in the console:

This confirms that the distributed build is discovering the workers.

2. Ensure Connection to Workers

Shortly after a distributed build starts, FASTBuild will start connecting to the available FBuildWorkers. Verify that your workers are being connected to by checking the UI. (If you are troubleshooting, you may like to limit your setup to one worker so you can control which workers will be used.)

Failure to establish any connections could indicate a routing or firewall problem on your network.

3. Check Firewall Rules

If you are using a firewall, make sure it is not blocking network connections from the FBuild.exe to the FBuildworker.exe(s). FASTBuild uses port 31264.

1. Ensure Compatible Compiler

Make sure the compiler being used is compatible with network distribution, as described here.

2. Compiler() Setup

Ensure your compiler is configured using the Compiler() function in the BFF config. If you are using a compiler (such as MSVC) that requires additional DLLs, be sure to configure those as well (see Compiler() for more details).

3. Ensure Compatible Options

Some compiler options prevent distribution as described here. Use -showcmds to ensure none of those options are on your command line.

If everything is working, you should see output similar to the following for any distributed tasks:

If things still don't seem to be working, or are not working as expected, you can obtain more information about what is going on use the -distverbose command line option.