If you’re trying to run the Mach examples or similar, you may be running into one of these known issues.
If you are using nixOS, we have tips on how to use Mach with it here.
File not found
If you encounter an error like this:
Windows does not have symlinks enabled, or Git is not configured to use them. This is very annoying and has been reported to Microsoft.
Two solutions exist:
- Enable symlinks in Windows:
- Build and run native Windows binaries from inside WSL:
zig build -Dtarget=x86_64-windows textured-cube
- Run the native Windows exe in
“SSL certificate problem: unable to get local issuer certificate”
This is a curl SSL CA issue, you may want to Google for proper solutions on your system. That said, you can
set CURL_INSECURE=true and retry to disable SSL verification if you want to workaround the issue.
Unresponsive white window
You may be encountering this issue:
- Symptoms: unresponsive white window, Windows 11
- Suspected cause: Corsair iCue, other bad system drivers
- Workaround: reboot Windows
How can I switch between Wayland/X11?
Mach builds with support for both Wayland and X11 in the same binary. By default, Mach will make use of X11 if it is available.
You can force the use of Wayland by setting
DISPLAY to an empty string, e.g.
“Error: vkCreateInstance failed with VK_ERROR_INCOMPATIBLE_DRIVER”
Some distros require packages to be installed to support the Vulkan graphics API.
For instance, Arch Linux has specific packages for Nvidia, Intel and AMD GPUs.
You may also try using OpenGL using the env var
“Error: Couldn’t load Vulkan. Searched /tmp/mach/gpu/zig-out/bin/libvulkan.so.1”
We’re aware of a bug failing to find
libvulkan.so on some Linux distros such as Guix.
Error: Couldn't load Vulkan. Searched /tmp/mach/gpu/zig-out/bin/libvulkan.so.1, /tmp/mach/gpu/zig-out/bin/libvulkan.so.1, libvulkan.so.1. at operator() (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:198) at Initialize (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:203) at Create (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:165) at operator() (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:420) found Null backend on CPU adapter: Null backend,
This is a bug in Dawn, you can workaround it for now by specifying the path to
libvulkan.so on your system
LD_PRELOAD like e.g.:
Choosing a different GitHub download mirror (Chinese users)
zig build on the first time around will download a 20-30MB file of Dawn (Google’s WebGPU implementation) from https://github.com/hexops/mach-gpu-dawn/releases - the build system uses
curl to do this automatically. You can of course build Dawn from source using
DAWN_FROM_SOURCE=true zig build, but this will require a clone of the Dawn sources which are a larger download and takes a few minutes to build as it is a large C++ codebase.
Users in Chinese mainland may find that download speeds to github.com are too slow (hours to download a 30 MB file), and apparently it is common to use GitHub mirror sites like https://doc.fastgit.org to download files from GitHub.
You can have Mach use such websites by setting an environment variable e.g.: