From 1f9afebbf539b1c51ee80020882f81d8d9b3987b Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sun, 3 May 2026 17:52:55 -0500 Subject: [PATCH] [ota] Make partition-table verify errors actionable When the running app does not fit any slot in the new partition table, the user has almost certainly picked the wrong migration .bin for their device. Replace the generic "No compatible app partition found" error with one that prints the running app's offset, used size, and the size limit a migration method must clear, plus an explicit reassurance that no flash content has been modified yet. Same treatment for the otadata-overlap case: include the running app offset/size and tell the user to pick a different migration method. Verification phase is non-destructive, so these errors are recoverable by retrying with the correct .bin -- the new wording makes that explicit so users don't lose time on a brick scare they aren't in. No code-flow change; only log message wording. --- esphome/components/ota/ota_partitions_esp_idf.cpp | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/esphome/components/ota/ota_partitions_esp_idf.cpp b/esphome/components/ota/ota_partitions_esp_idf.cpp index 3a79136c617..2a2ed577f1e 100644 --- a/esphome/components/ota/ota_partitions_esp_idf.cpp +++ b/esphome/components/ota/ota_partitions_esp_idf.cpp @@ -131,7 +131,14 @@ OTAResponseTypes IDFOTABackend::validate_new_partition_table_(uint32_t running_a } if (new_app_part_index == -1 && new_app_part_index_with_copy == -1) { - ESP_LOGE(TAG, "No compatible app partition found in the new partition table"); + // Most likely cause: the user picked the wrong migration .bin for their running app's size. + // Rejecting here is non-destructive (no flash op has run yet); the user can safely retry with + // a different .bin. Log enough info that they can pick the right method without guessing. + ESP_LOGE(TAG, + "Running app at 0x%X (%u bytes used) does not fit any compatible slot in the new " + "partition table. Pick a migration method whose size limit is at least %u bytes and " + "retry; no flash content was modified.", + running_app_offset, running_app_size, running_app_size); return OTA_RESPONSE_ERROR_PARTITION_TABLE_VERIFY; } if (app_partitions_found < 2) { @@ -147,7 +154,11 @@ OTAResponseTypes IDFOTABackend::validate_new_partition_table_(uint32_t running_a return OTA_RESPONSE_ERROR_PARTITION_TABLE_VERIFY; } if (otadata_overlap) { - ESP_LOGE(TAG, "New otadata partition overlaps with running app"); + ESP_LOGE(TAG, + "New otadata partition overlaps with the running app at 0x%X (size %u). The chosen " + "partition table is not compatible with this device's current flash layout; pick a " + "different migration method.", + running_app_offset, running_app_size); return OTA_RESPONSE_ERROR_PARTITION_TABLE_VERIFY; }