ESP-IDF CMake "could not find ... toolchain" in CI

idf.py drives a CMake configure step that requires the ESP cross-compiler. If the IDF tools were never installed, CMake cannot find the toolchain executable and aborts configuration before any source compiles.

What this error means

idf.py build fails during CMake configuration with a message that the C compiler is not found, for example the xtensa-esp32-elf-gcc toolchain cannot be located.

CMake Error at /esp-idf/tools/cmake/toolchain-esp32.cmake:
  Could not find compiler set in environment variable CC:
  xtensa-esp32-elf-gcc.

Common causes

The IDF tools were not installed

Cloning ESP-IDF does not install the toolchains. Without running install.sh, the cross compilers are absent and CMake cannot find them.

export.sh was not sourced after installing tools

Even with tools installed, export.sh must run so the toolchain is on PATH for the CMake configure step.

How to fix it

Install tools then source the environment

1. Run install.sh <target> to install the toolchains for your chip.
2. Source export.sh in the same step as the build.
3. Run idf.py so CMake finds the compiler.

- run: |
    ./install.sh esp32
    . ./export.sh
    idf.py set-target esp32
    idf.py build
  working-directory: esp-idf

Let the CI action provision the toolchain

The official action installs the toolchain for the requested target automatically.

- uses: espressif/esp-idf-ci-action@v1
  with:
    esp_idf_version: v5.2.1
    target: esp32

How to prevent it

• Run install.sh for your target before building.
• Source export.sh in the same step as idf.py.
• Cache the IDF tools directory so toolchains persist between runs.

Related guides