From 35e5c7c7c353ab8182d3c74a65b434e1738ec2e3 Mon Sep 17 00:00:00 2001
From: guillempages <guillempages@users.noreply.github.com>
Date: Sat, 13 Jun 2026 23:40:49 +0200
Subject: [PATCH] [runtime_image] Improve error logging (#16943)

---
 esphome/components/online_image/online_image.cpp |  3 ++-
 esphome/components/runtime_image/image_decoder.h | 16 ++++++++++++++++
 .../components/runtime_image/jpeg_decoder.cpp    | 16 ++++++++++++++--
 esphome/components/runtime_image/png_decoder.cpp |  1 +
 4 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/esphome/components/online_image/online_image.cpp b/esphome/components/online_image/online_image.cpp
index a5a3ea5104..22bce4cc41 100644
--- a/esphome/components/online_image/online_image.cpp
+++ b/esphome/components/online_image/online_image.cpp
@@ -1,4 +1,5 @@
 #include "online_image.h"
+#include "esphome/components/runtime_image/image_decoder.h"
 #include "esphome/core/log.h"
 #include <algorithm>
 
@@ -181,7 +182,7 @@ void OnlineImage::loop() {
       auto consumed = this->feed_data(this->download_buffer_.data(), this->download_buffer_.unread());
 
       if (consumed < 0) {
-        ESP_LOGE(TAG, "Error decoding image: %d", consumed);
+        ESP_LOGE(TAG, "Error decoding image: %s", esphome::runtime_image::decode_error_to_string(consumed));
         this->end_connection_();
         this->download_error_callback_.call();
         return;
diff --git a/esphome/components/runtime_image/image_decoder.h b/esphome/components/runtime_image/image_decoder.h
index 926108a8a0..c68ea5720b 100644
--- a/esphome/components/runtime_image/image_decoder.h
+++ b/esphome/components/runtime_image/image_decoder.h
@@ -7,8 +7,24 @@ enum DecodeError : int {
   DECODE_ERROR_INVALID_TYPE = -1,
   DECODE_ERROR_UNSUPPORTED_FORMAT = -2,
   DECODE_ERROR_OUT_OF_MEMORY = -3,
+  DECODE_ERROR_INTERNAL_DECODER_ERROR = -4,
 };
 
+constexpr const char *decode_error_to_string(int error) {
+  switch (error) {
+    case DECODE_ERROR_INVALID_TYPE:
+      return "Invalid type";
+    case DECODE_ERROR_UNSUPPORTED_FORMAT:
+      return "Unsupported format";
+    case DECODE_ERROR_OUT_OF_MEMORY:
+      return "Out of memory";
+    case DECODE_ERROR_INTERNAL_DECODER_ERROR:
+      return "Internal decoder error";
+    default:
+      return "Unknown error";
+  }
+}
+
 class RuntimeImage;
 
 /**
diff --git a/esphome/components/runtime_image/jpeg_decoder.cpp b/esphome/components/runtime_image/jpeg_decoder.cpp
index dcaa07cd58..c46e86fd0d 100644
--- a/esphome/components/runtime_image/jpeg_decoder.cpp
+++ b/esphome/components/runtime_image/jpeg_decoder.cpp
@@ -89,9 +89,21 @@ int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
     return DECODE_ERROR_OUT_OF_MEMORY;
   }
   if (!this->jpeg_.decode(0, 0, 0)) {
-    ESP_LOGE(TAG, "Error while decoding.");
+    auto error = this->jpeg_.getLastError();
+    ESP_LOGE(TAG, "Error while decoding: %d", error);
     this->jpeg_.close();
-    return DECODE_ERROR_UNSUPPORTED_FORMAT;
+    switch (error) {
+      case JPEG_ERROR_MEMORY:
+        return DECODE_ERROR_OUT_OF_MEMORY;
+      case JPEG_UNSUPPORTED_FEATURE:
+        return DECODE_ERROR_UNSUPPORTED_FORMAT;
+      case JPEG_INVALID_FILE:
+      case JPEG_INVALID_PARAMETER:
+        return DECODE_ERROR_INVALID_TYPE;
+      case JPEG_DECODE_ERROR:
+      default:
+        return DECODE_ERROR_INTERNAL_DECODER_ERROR;
+    }
   }
   this->decoded_bytes_ = size;
   this->jpeg_.close();
diff --git a/esphome/components/runtime_image/png_decoder.cpp b/esphome/components/runtime_image/png_decoder.cpp
index 591504328d..12bce0d284 100644
--- a/esphome/components/runtime_image/png_decoder.cpp
+++ b/esphome/components/runtime_image/png_decoder.cpp
@@ -95,6 +95,7 @@ int HOT PngDecoder::decode(uint8_t *buffer, size_t size) {
   auto fed = pngle_feed(this->pngle_, buffer, size);
   if (fed < 0) {
     ESP_LOGE(TAG, "Error decoding image: %s", pngle_error(this->pngle_));
+    return DECODE_ERROR_INTERNAL_DECODER_ERROR;
   } else {
     this->decoded_bytes_ += fed;
   }