Steps to follow if the build fails

I have noticed that many people has problems building Rack. Very often is because the dependencies are not built correctly, and little often is because there’s an actual problem with the build system.

Before creating a new github issue or a topic in the forum try these steps.

1.- Check that you are building the version you want to build. Checkout the branch/tag of the version you want. Currently most of the people are trying to build the branch for v1.0. To do so, run the following command inside the Rack code folder:

$ git checkout v1

If you were already on that branch. Check that you have the latest code by running:

$ git pull

2.- Check again that you have all the tools needed to build. Check the section Setting up your development environment in the manual.

Check as well that you have the latest versions of the tools:


$ pacman -Syu
$ pacman -Su

Linux (Ubuntu/Debian):

$ sudo apt update
$ sudo apt upgrade


$ brew update
$ brew upgrade

3.- Make sure your repository is clean (including the dep folder) by running:

$ make clean
$ cd dep
$ make clean
$ cd ..

Alternatively. You can clone a new repository and follow the steps in point 1 to get the correct source code.

4.- Make sure that the dependencies are updated. If you are not using a newly cloned repository, the dependencies may be out of sync. Run the following commands:

$ git submodule sync
$ git submodule update --init --recursive

5.- Start the build with:

$ make dep
$ make

6.- Check that the variable RACK_DIR is not set pointing to a different location. Run the command:

$ echo $RACK_DIR

If the result is empty, then it’s not set. If you get a path that points to a directory different from the one you are building, this can cause build failures. To temporarily remove the variable run:

$ unset RACK_DIR

It’s recommended that you find how you have set the RACK_DIR variable and either update it or remove it.

If after following these steps the build still fails, try again but in a newly created clone.

If you still get errors, use the search function in the VCV Rack GitHub issues to find if someone else has reported the same error. If not, create a new issue and provide all the necessary information.


Very good advice. I would add to make sure you have updated the required packages with pacman, brew, or apt-get as documented in the build instructions. And, if you have an old repo (not newly cloned) your steps are good, but if that fails, try re-cloning to a new folder ( with git clone my-new-folder-name).


miss the info on how to switch and track the correct branch (v1)

many were trying to build the v1 using the master


@synthi @Squinky Updated!


Oh yes… It works… Thank You veri much!

VERY, of course…

1 Like

I found a very stupid way to break the build, thought I’d share… set RACK_DIR, somewhere it stays permanent (System Settings in Windows). Then forget about it, start from scratch months later and wonder why weird errors happen as includes are pulled from the old, not the new directory…

I added your problem to the list of steps. Thanks!

1 Like