PlatformIO "Unknown board ID" build error in CI

PlatformIO read the board value from your environment in platformio.ini and found no board definition with that ID in any installed platform. The name is wrong, or the platform that defines it was never installed on the runner.

What this error means

A pio run step stops with "Error: Unknown board ID '<name>'". It happens on a clean CI runner even when the same project builds on a developer machine that already has the platform cached.

Error: Unknown board ID 'esp32doit-devkit-v1x'

Common causes

The board ID is misspelled or renamed

The board = ... value does not match any known board ID. A typo or an old name that was renamed in a newer platform release produces this error.

The platform that defines the board is not installed

Board IDs come from installed platforms. On a clean runner the platform is absent until PlatformIO installs it, so the ID resolves to nothing.

How to fix it

Use the exact board ID from the registry

1. List boards for your platform with pio boards <platform> and copy the exact ID.
2. Correct the board = ... value in the matching environment in platformio.ini.
3. Re-run pio run to confirm the board now resolves.

pio boards espressif32 | grep -i devkit

Declare the platform so the board is available

Set platform in the environment so PlatformIO installs the package that defines the board before building.

[env:esp32dev]
platform = espressif32
board = esp32doit-devkit-v1
framework = arduino

How to prevent it

• Copy board IDs from pio boards, never type them by hand.
• Pin the platform so the board definition is always installed.
• Cache ~/.platformio so platform packages persist across CI runs.

Related guides