Debugging Arduino 2.3.6 Postbuild Errors: ESP32 Custom Scripts & Bin Merging

The Short Answer: Fixing the Arduino 2.3.6 Postbuild Error

When you are compiling custom firmware for an ESP32 and need to merge binaries, generate OTA payloads, or run custom Python scripts after compilation, the Arduino IDE 2.3.x build system (powered by arduino-cli under the hood) enforces strict path resolution and sandboxing. If your custom hook fails, you are likely hitting a path or executable alias issue introduced in the 2.x architecture.

The first three things to check when it fails:

1. Executable Alias: Arduino IDE 2.3.x does not automatically map python to python3 on macOS/Linux. Your platform.txt must explicitly call the resolved tool path.
2. Path Variables: Hardcoding python3 postbuild.py fails in the CLI sandbox. You must use the IDE’s internal variable: {runtime.tools.python3.path}.
3. File Permissions: If calling a shell script directly, ensure it has execute permissions (chmod +x postbuild.sh) before triggering the build.

Target Board, Parts List, and Pin Mapping

To verify that our postbuild hook correctly processes the final .bin file and that the hardware flashes successfully, we will use a standard ESP32 development board with a basic status indicator. This proves the build pipeline and the physical silicon are both functioning.

Parts List

• Microcontroller: ESP32-WROOM-32 DevKit V1 (30-pin variant, CP2102 USB-UART bridge)
• Indicator: 5mm Red LED
• Current Limiting: 220Ω through-hole resistor (1/4W)
• Wiring: 22 AWG solid core jumper wires
• Software: Arduino IDE 2.3.x (with ESP32 Core v3.0.x installed via Board Manager)

Pin Mapping Table

The Exact Error String & Ranked Causes

The migration from the legacy Java-based Arduino IDE 1.8.x to the modern 2.x architecture fundamentally changed how platform.txt recipes are executed. The build system now uses arduino-cli, which isolates toolchains and strictly enforces declared paths.

Here is the ranked decision path for diagnosing the exec: "python": executable file not found or permission denied errors:

Step-by-Step Fix: Configuring the Postbuild Hook

Let’s implement a postbuild hook that automatically merges the ESP32 bootloader, partition table, and application binary into a single merged_ota.bin file at 0x0 offset, ready for web-based OTA updates. This is a common requirement for commercial IoT deployments.

Step 1: Locate your platform.txt
On Linux/macOS, navigate to ~/.arduino15/packages/esp32/hardware/esp32/3.0.x/. On Windows, check C:\Users\[User]\AppData\Local\Arduino15\packages\esp32\hardware\esp32\3.0.x\.

Step 2: Inject the Postbuild Recipe
Open platform.txt in a text editor. Scroll to the bottom and add the following hook. Notice the use of the {runtime.tools.python3.path} variable to satisfy the IDE 2.3.x sandbox requirements.

## Custom Postbuild Hook for ESP32 Bin Merging
recipe.hooks.postbuild.1.pattern="{runtime.tools.python3.path}" "{runtime.platform.path}"/tools/postbuild_merge.py "{build.path}" "{build.project_name}" "{runtime.platform.path}"/tools
recipe.hooks.postbuild.1.pattern.windows="{runtime.tools.python3.path}" "{runtime.platform.path}\tools\postbuild_merge.py" "{build.path}" "{build.project_name}" "{runtime.platform.path}\tools"

Step 3: Create the Python Script
Create postbuild_merge.py in the core’s tools directory. This script leverages Espressif’s official esptool to merge the binaries.

import sys, os, subprocess

build_path = sys.argv[1]
project_name = sys.argv[2]
tools_path = sys.argv[3]

# ESP32 standard memory map offsets
bootloader = os.path.join(build_path, "bootloader.bin")
partitions = os.path.join(build_path, "partitions.bin")
app_bin = os.path.join(build_path, f"{project_name}.bin")
output_bin = os.path.join(build_path, "merged_ota.bin")

cmd = [
    sys.executable, "-m", "esptool", "--chip", "esp32", "merge_bin",
    "-o", output_bin, "--flash_mode", "dio", "--flash_size", "4MB",
    "0x1000", bootloader, "0x8000", partitions, "0x10000", app_bin
]

try:
    subprocess.run(cmd, check=True)
    print(f"[POSTBUILD] Successfully merged to {output_bin}")
except subprocess.CalledProcessError as e:
    print(f"[POSTBUILD ERROR] esptool failed: {e}")
    sys.exit(1)

Complete Compilable Test Code (ESP32 Watchdog)

Below is the firmware you will compile to test the pipeline. It targets the ESP32-WROOM-32 DevKit V1. It includes hardware watchdog initialization and explicit error handling to ensure the board doesn’t brownout or hang silently during boot—a common issue when power delivery is marginal on cheap USB cables.

/*
 * Target Board: ESP32-WROOM-32 DevKit V1 (30-pin)
 * Purpose: Postbuild Pipeline Verification & Hardware Watchdog Test
 * Arduino IDE: 2.3.x | ESP32 Core: 3.0.x
 */

#include <Arduino.h>
#include <esp_task_wdt.h>

// --- PIN DEFINITIONS ---
#define STATUS_LED_PIN 2  // Native boot-strapping pin, usually has onboard LED
#define WDT_TIMEOUT_SEC 5 // Watchdog timeout in seconds

void setup() {
  // Initialize Serial with a timeout to prevent hanging if USB isn't connected
  Serial.begin(115200);
  unsigned long serialTimeout = millis() + 2000;
  while (!Serial && millis() < serialTimeout) {
    delay(10);
  }
  
  Serial.println("[BOOT] ESP32 Postbuild Verification Starting...");

  // Configure Status LED
  pinMode(STATUS_LED_PIN, OUTPUT);
  
  // Initialize Task Watchdog Timer (TWDT)
  esp_err_t wdt_err = esp_task_wdt_init(WDT_TIMEOUT_SEC, true); // panic on timeout
  if (wdt_err != ESP_OK) {
    Serial.printf("[ERROR] Failed to init WDT: %d\n", wdt_err);
    // Fallback: Blink rapidly to indicate WDT failure
    while(1) {
      digitalWrite(STATUS_LED_PIN, !digitalRead(STATUS_LED_PIN));
      delay(50);
    }
  }
  esp_task_wdt_add(NULL); // Subscribe current task to TWDT
  
  Serial.println("[OK] WDT Initialized. Entering main loop.");
  Serial.println("[INFO] If postbuild hook ran, check build folder for merged_ota.bin");
}

void loop() {
  // Reset the watchdog timer to prevent reboot
  esp_task_wdt_reset();
  
  // Normal application logic
  digitalWrite(STATUS_LED_PIN, HIGH);
  delay(500);
  
  esp_task_wdt_reset(); // Reset again before long operations
  
  digitalWrite(STATUS_LED_PIN, LOW);
  delay(500);
}

Decision Path: Which Postbuild Strategy to Choose?

Not every project requires merging binaries. Use this decision tree to determine the exact tool and strategy for your postbuild hook, terminating in a concrete recommendation for your specific scenario.

Extending and Simplifying Your Build Pipeline

Once your Arduino 2.3.6 postbuild hook is functioning locally, you will eventually want to move away from the GUI to ensure reproducible builds across your team.

How to Simplify the Local Build

The Arduino IDE GUI caches old platform.txt files aggressively. If you edit the hook and it doesn’t trigger, do not restart your computer. Instead, delete the ~/.arduino15/packages/esp32/tools/ cache directory, or simply switch to the Arduino CLI for your terminal builds. The CLI respects platform.txt changes instantly upon the next arduino-cli compile command.

How to Extend to CI/CD (GitHub Actions)

To extend this pipeline to a production environment, strip out the IDE-specific variables and hardcode the paths in a GitHub Actions workflow. Use the official arduino/compile-sketches action, and add a secondary step that runs your Python merging script against the compiled artifacts. This removes the reliance on the local developer’s $PATH environment entirely, eliminating the executable file not found error permanently.