Fixing Zephyr Build Errors from Missing Device Tree Overlays

Zephyr build failures due to missing device tree overlays are a common frustration for developers working with custom boards or modifying existing board support. The error typically surfaces during the west build step, halting compilation with a cryptic “File not found” message. This article provides a systematic approach to diagnosing and resolving these overlay-related build failures, ensuring your Zephyr project compiles successfully.

Problem Statement: The Missing Overlay Build Error

When building a Zephyr application for a custom board, you might encounter an error like:

*** Error: File not found: 'boards/arm/stm32f4_discovery/stm32f4_discovery.overlay'

This error indicates that the Zephyr build system expects to find a device tree overlay file named stm32f4_discovery.overlay in the board directory, but the file is missing. The build fails during the devicetree compilation phase, preventing further progress.

Root Cause Analysis: Why Zephyr Expects the Overlay

Zephyr’s build process uses the device tree to describe hardware dependencies. Board definitions often include optional overlay files for hardware variations. When a board’s .dts file references an overlay via an #include directive, the build system mandates that the referenced file exists. If the file is absent, the build fails with a “File not found” error.

Common scenarios leading to missing overlays:

1. Board modification: Customizing an existing board and forgetting to add the corresponding overlay file.
2. Incorrect overlay name: Typos in the overlay filename within the .dts file.
3. Missing overlay directory: Placing the overlay in an unexpected location not searched by Zephyr.
4. Case sensitivity issues: Filesystem case sensitivity causing mismatches (e.g., Board.overlay vs board.overlay).

Solution Approach: Locate and Add the Missing Overlay

Step 1: Identify the Missing Overlay from Build Logs

Examine the full build output to pinpoint the exact missing file. The error message typically includes the searched path:

[devicetree] Error: File not found: 'stm32f4_discovery.overlay'

Note the filename and the directory Zephyr searched (usually the board directory under boards/).

Step 2: Verify Overlay Existence and Location

Check if the overlay file exists in the expected location:

ls -la boards/arm/stm32f4_discovery/stm32f4_discovery.overlay

If the file is missing, create it. If it exists elsewhere, move it to the correct directory or adjust the #include path in the .dts file.

Step 3: Create the Missing Overlay File

Create a basic overlay file if none exists. For example, stm32f4_discovery.overlay:

/ {
};

This empty overlay satisfies the build requirement while allowing you to add specific configurations later.

Step 4: Reference the Overlay in the Board DTS

Ensure the board’s .dts file includes the overlay. In stm32f4_discovery.dts, you should see:

#include "stm32f4_discovery.overlay"

If absent, add the line. If present but incorrect, fix the filename to match exactly.

Step 5: Rebuild and Verify

Run west build again. The build should now proceed past the devicetree step. If additional errors appear, repeat the process for any other missing overlays.

Complete Working Example: Fixing STM32F4 Discovery Build

Consider a scenario where you’re building for STM32F4 Discovery board and encountering a missing overlay error.

1. Identify the Missing Overlay

Build output shows:

[devicetree] Error: File not found: 'stm32f4_discovery.overlay'

2. Check Current Directory

$ ls boards/arm/stm32f4_discovery/
stm32f4_discovery.dts  stm32f4_discovery.h  ...

The overlay file is indeed missing.

3. Create the Overlay File

$ touch boards/arm/stm32f4_discovery/stm32f4_discovery.overlay

4. Verify Board DTS Includes the Overlay

Check stm32f4_discovery.dts:

/* ... */
#include "stm32f4_discovery.overlay"
/* ... */

The include is present.

5. Rebuild

$ west build -b stm32f4_discovery samples/basic/blinky

The build now succeeds, progressing past the devicetree step.

ASCII Art Diagram: Overlay Inclusion Flow

The following diagram illustrates how Zephyr locates and includes device tree overlays during the build process:

+---------------------+     +---------------------+     +---------------------+
|  Board Definition   |     |  Overlay File       |     |  Build System       |
|  (stm32f4_discovery.|     |  (stm32f4_discovery.|     |  (devicetree.py)    |
|   dts)              |     |   overlay)          |     |                     |
+---------------------+     +---------------------+     +---------------------+
          |                         |                         |
          | #include "stm32f4_discovery.overlay" |                         |
          |-------------------------->|                         |
          |                         |                         |
          |                         | File exists? ----------->| Yes
          |                         |                         |  |
          |                         |                         |  v
          |                         |                     +---------------------+
          |                         |                     |  Continue Build     |
          |                         |                     +---------------------+
          |                         |                         |
          |                         | No                    |
          |                         |<----------------------+
          |                         |  Error: File not found  |
          |                         |                         |
          +-------------------------<-------------------------+

Verification and Testing

After adding the missing overlay:

1. Rebuild the project with west build.
2. Ensure the build progresses beyond the devicetree step.
3. Flash the resulting binary to verify functionality is unaffected (an empty overlay does not alter hardware configuration).
4. If adding specific configurations to the overlay, test those features explicitly.

Summary and Key Takeaways

• Zephyr build failures due to missing overlays are resolvable by identifying the missing file from build logs.
• Always verify the exact filename and path Zephyr expects, paying attention to case sensitivity.
• Create missing overlay files in the board directory or adjust the .dts include accordingly.
• An empty overlay file (/ { };) is sufficient to resolve the build error while allowing future customization.
• Systematic inspection of build logs and board definitions prevents recurrence of this issue.

Related Reading

• Device Tree Overlays in Zephyr
• STM32F4 Discovery Board Documentation
• Zephyr Build System Overview
• West Zephyr’s Meta-Tool

References

1. Zephyr Project Documentation, “Device Tree Overlays”, https://docs.zephyrproject.org/latest/build/dts/howtos.html
2. STMicroelectronics, “STM32F4 Discovery kit with STM32F407VG MCU”, https://web.archive.org/web/20241113131657/https://www.st.com/en/evaluation-tools/stm32f4discovery.html
3. Zephyr Project Documentation, “Build System”, https://docs.zephyrproject.org/latest/build/
4. Zephyr Project Documentation, “West - Zephyr’s Meta-Tool”, https://docs.zephyrproject.org/latest/guides/west/
5. Linux Device Tree Documentation, “Device Tree Usage”, https://www.kernel.org/doc/Documentation/devicetree/usage-model.txt