CMake "Could not find toolchain file" in CI

By Kaveh Alemi·Latchkey

CMake was told to use a toolchain file via CMAKE_TOOLCHAIN_FILE, but the path does not resolve on the runner. It is often relative to the wrong directory, or the file (a vcpkg or cross-compile toolchain) was never fetched.

What this error means

Configuration fails immediately with "CMake Error: Could not find toolchain file: <path>", before any compiler probe runs.

CMake Error: Could not find toolchain file:
/home/runner/work/app/app/vcpkg/scripts/buildsystems/vcpkg.cmake

Common causes

The toolchain path does not exist on the runner

A vcpkg or cross-compile toolchain file was not checked out or fetched, so the path CMake was given is empty.

The path is relative to the wrong directory

A relative CMAKE_TOOLCHAIN_FILE resolves against the working directory, which differs in CI from local runs.

How to fix it

Pass an absolute, existing toolchain path

1. Ensure the toolchain file is present (bootstrap vcpkg or add the cross toolchain).
2. Pass CMAKE_TOOLCHAIN_FILE as an absolute path.
3. Re-run configure so the toolchain loads first.

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake

Bootstrap the toolchain provider first

For vcpkg, check it out and bootstrap it before configuring so the toolchain file exists.

git clone https://github.com/microsoft/vcpkg
./vcpkg/bootstrap-vcpkg.sh

How to prevent it

• Always pass toolchain paths as absolute, not relative.
• Fetch or bootstrap the toolchain provider before the configure step.
• Reference ${{ github.workspace }} instead of assuming the working directory.

Frequently asked questions

Related guides

References

• CMake documentation
• GitHub Actions documentation