Arduino CLI "Platform ... not installed" build error in CI

arduino-cli read the platform portion of your FQBN and found no matching core installed. On a clean runner the cores index is empty until you update it and install the core for your board.

What this error means

An arduino-cli compile step fails with "Error during build: platform <vendor:arch> not installed" or "platform not installed, please install it by running ...".

arduino-cli

Error during build: Platform 'esp32:esp32' not installed, please install it by running 'arduino-cli core install esp32:esp32'.

Common causes

The core was never installed on the runner

A fresh runner has no cores. Without an explicit arduino-cli core install, the platform in your FQBN is absent.

The vendor index was not updated

Third-party cores need their package URL added and core update-index run first, or the core cannot be found to install.

How to fix it

Install the core before compiling

Add any third-party board manager URL to the config.
Run arduino-cli core update-index.
Install the exact core named in the FQBN, then compile.

Terminal

arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:esp32

Cache the Arduino data directory

Persist the installed cores so they do not reinstall every run.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.arduino15
    key: arduino-${{ hashFiles('**/*.ino') }}

How to prevent it

Install the core as an explicit CI step before compiling.
Add third-party board URLs and run core update-index first.
Cache ~/.arduino15 so cores persist between runs.