ESP-IDF App Descriptor missing in your`esp-idf` application.

[hazer-hazer]

Hi, I encountered this error after updating to the latest version of espflash:

Error:   × ESP-IDF App Descriptor (https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-
  │ reference/system/app_image_format.html#application-description) missing in your`esp-idf`
  │ application.

Cargo.toml:

# ...
esp-bootloader-esp-idf = "0.1.0"
esp-hal = { version = "^1.0.0-beta.0", features = [
  "esp32c3",
  "unstable",
  "log",
] }
esp-hal-embassy = { version = "0.7", features = ["esp32c3"] }
# ...

Error does not appear on espflash@3.3.0

[crazyjay97]

same error here when i run espflash flash use espflash v4.0.1
espflash v3.3.0 is ok
[2025-07-16T08:22:11Z WARN ] Monitor options were provided, but --monitor/-M flag isn't set. These options will be ignored. [2025-07-16T08:22:11Z INFO ] Serial port: '/dev/cu.usbmodem2137301' [2025-07-16T08:22:11Z INFO ] Connecting... [2025-07-16T08:22:12Z INFO ] Using flash stub Error: × ESP-IDF App Descriptor (https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/app_image_format.html#application-description) missing in youresp-idf application.

[mawoka-myblock]

Here's the solution: https://github.com/esp-rs/esp-hal/releases/tag/esp-hal-v1.0.0-rc.0

I find it quite unlucky that the new version of espflash is released without the needed note or documentation on how to implement the change.

[MabezDev]

Using a recent esp-hal version (1.0.0-beta.1 and higher iirc) will produce a better error:

espflash/espflash/src/image_format/idf.rs

Lines 815 to 816 in b993a42

	if !has_app_desc {
	if is_esp_hal {

.

Can you confirm that, or is this a bug?

[SergioGasquez]

Hi @hazer-hazer, do you have any updates regarding this issue?

[MabezDev]

A user on matrix reported a similar issue, and provided the ELF for debugging: https://drive.google.com/file/d/138AJwjKcE3LC9jUwflzR-lpaBEF3jQFA/view

[SergioGasquez]

I think we are seeing two different issues here, the one from the OP related with app desc and Image contains multiple DROM segments. Only the last one will be mapped. which appears on the elf shared by @MabezDev, I did some tests with the latter, and it also appears in espflash@3.3 and esptool@4.8.1

[ImplFerris]

Image contains multiple DROM segments. Only the last one will be mapped.

I checked it with esptool, the DROM gets split into two. This seems to be the reason behind the error message.

7 segments

Segment 1: len 0x00100 load 0x3f400020 file_offs 0x00000018 [DROM]
Segment 2: len 0x00050 load 0x3ffb0000 file_offs 0x00000120 [BYTE_ACCESSIBLE,DRAM]
Segment 3: len 0x0f2f4 load 0x3f400180 file_offs 0x00000178 [DROM]
Segment 4: len 0x00674 load 0x3ffb0050 file_offs 0x0000f474 [BYTE_ACCESSIBLE,DRAM]
Segment 5: len 0x00520 load 0x40080000 file_offs 0x0000faf0 [IRAM]
Segment 6: len 0x1aa0c load 0x400d0020 file_offs 0x00010018 [IROM]
Segment 7: len 0x00d04 load 0x40080520 file_offs 0x0002aa2c [IRAM]

The error message i belive it is coming from "bootloader_utility.c" because of two different DROM segments there.

// Find DROM & IROM addresses, to configure MMU mappings
for (int i = 0; i < data->image.segment_count; i++) {
    const esp_image_segment_header_t *header = &data->segments[i];
    if (header->load_addr >= SOC_DROM_LOW && header->load_addr < SOC_DROM_HIGH) {
        if (drom_addr != 0) {
            ESP_EARLY_LOGE(TAG, MAP_ERR_MSG, ESP_LOG_ATTR_STR("DROM"));  // <- Error origination
        } else {
            ESP_EARLY_LOGD(TAG, "Mapping segment %d as %s", i, ESP_LOG_ATTR_STR("DROM"));
        }
        drom_addr = data->segment_data[i];
        drom_load_addr = header->load_addr;
        drom_size = header->data_len;
    }
   ...
   ...
}

I check with different esp-hal and espflash version

esp-hal version: 1.0.0-beta.0

There are 33 section headers, starting at offset 0x4097d0:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .rwtext           PROGBITS        40080400 00e400 000a1c 00  AX  0   0  4
  [ 2] .rwtext.wifi      PROGBITS        40080e1c 026b42 000000 00   W  0   0  1
  [ 3] .text             PROGBITS        400d0020 00f020 017b22 00  AX  0   0  4
  [ 4] .data             PROGBITS        3ffb0000 001000 00055c 00  WA  0   0  8
  [ 5] .bss              NOBITS          3ffb0560 001560 020148 00  WA  0   0  8
  [ 6] .noinit           NOBITS          3ffd06a8 000000 000000 00  WA  0   0  4
  [ 7] .data.wifi        PROGBITS        3ffd06a8 026b42 000000 00  WA  0   0  1
  [ 8] .rodata           PROGBITS        3f400580 001580 00bbd0 00   A  0   0 128
  [ 9] .rodata.wifi      PROGBITS        3f40c150 026b44 000000 00  WA  0   0  4
  [10] .rtc_fast.text    PROGBITS        400c0000 026b44 000000 00   W  0   0  1
  [11] .defmt            PROGBITS        00000001 026b44 000018 00      0   0  1
  [12] .vectors          PROGBITS        40080000 00e000 000400 00  AX  0   0  4
  [13] .rtc_fast.dummy   PROGBITS        3ff80000 026b5c 000000 00   W  0   0  1
  [14] .rtc_fast.data    PROGBITS        3ff80000 026b5c 000000 00   W  0   0  1
  [15] .rtc_fast.bss     PROGBITS        3ff80000 026b5c 000000 00   W  0   0  1
  [16] .rtc_fast.pe[...] PROGBITS        3ff80000 026b5c 000000 00   W  0   0  1
  [17] .rtc_slow.text    PROGBITS        50000000 026b5c 000000 00   W  0   0  1
  [18] .rtc_slow.data    PROGBITS        50000000 026b5c 000000 00   W  0   0  1
  [19] .rtc_slow.bss     PROGBITS        50000000 026b5c 000000 00   W  0   0  1
  [20] .rtc_slow.pe[...] PROGBITS        50000000 026b5c 000000 00   W  0   0  1
  [21] .stack            PROGBITS        3ffd06a8 026b5c 000000 00   W  0   0  4
  [22] .debug_loc        PROGBITS        00000000 026b5c 0b5406 00      0   0  1
  [23] .debug_abbrev     PROGBITS        00000000 0dbf62 0013dc 00      0   0  1
  [24] .debug_info       PROGBITS        00000000 0dd33e 13950c 00      0   0  1
  [25] .debug_aranges    PROGBITS        00000000 21684a 004b40 00      0   0  1
  [26] .debug_ranges     PROGBITS        00000000 21b38a 027888 00      0   0  1
  [27] .debug_str        PROGBITS        00000000 242c12 176b17 01  MS  0   0  1
  [28] .comment          PROGBITS        00000000 3b9729 00003f 01  MS  0   0  1
  [29] .debug_line       PROGBITS        00000000 3b9768 0451b4 00      0   0  1
  [30] .symtab           SYMTAB          00000000 3fe91c 002b10 10     31 377  4
  [31] .strtab           STRTAB          00000000 40142c 00823e 00      0   0  1
  [32] .shstrtab         STRTAB          00000000 40966a 000163 00      0   0  1
Key to Flags:
  W (write), A (alloc), X (execute), M (merge), S (strings), I (info),
  L (link order), O (extra OS processing required), G (group), T (TLS),
  C (compressed), x (unknown), o (OS specific), E (exclude),
  D (mbind), p (processor specific)

Image saved with esp-flash version: 3.3.0

esptool.py v4.7.0
File size: 162672 (bytes)
Image version: 1
Entry point: 400d7384
7 segments

Segment 1: len 0x00018 load 0x00000001 file_offs 0x00000018 [PADDING]
Segment 2: len 0x00538 load 0x3ffb0000 file_offs 0x00000038 [BYTE_ACCESSIBLE,DRAM]
Segment 3: len 0x0bbd0 load 0x3f400580 file_offs 0x00000578 [DROM]
Segment 4: len 0x00024 load 0x3ffb0538 file_offs 0x0000c150 [BYTE_ACCESSIBLE,DRAM]
Segment 5: len 0x00e1c load 0x40080000 file_offs 0x0000c17c [IRAM]
Segment 6: len 0x03070 load 0x00000000 file_offs 0x0000cfa0 [PADDING]
Segment 7: len 0x17b24 load 0x400d0020 file_offs 0x00010018 [IROM]
Checksum: 71 (valid)

• Not able to save image with espflash 4.2.0

---

esp-hal version: 1.0.0-rc.1

There are 35 section headers, starting at offset 0x445274:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .rwtext           PROGBITS        40080400 012400 000f3c 00  AX  0   0  4
  [ 2] .rwtext.wifi      PROGBITS        4008133c 02f6a5 000000 00   W  0   0  1
  [ 3] .data             PROGBITS        3ffb0000 011000 000ad4 00  WA  0   0  8
  [ 4] .data.wifi        PROGBITS        3ffb0ad4 02f6a5 000000 00  WA  0   0  1
  [ 5] .bss              NOBITS          3ffb0ad8 011ad4 020128 00  WA  0   0  8
  [ 6] .noinit           NOBITS          3ffd0c00 000000 000000 00  WA  0   0  4
  [ 7] .rodata_desc      PROGBITS        3f400020 001020 000100 00   A  0   0  4
  [ 8] .rodata           PROGBITS        3f400180 001180 00f51c 00   A  0   0 128
  [ 9] .rodata.wifi      PROGBITS        3f40f69c 02f6a8 000000 00  WA  0   0  4
  [10] .text             PROGBITS        400d0020 014020 01b685 00  AX  0   0  4
  [11] .rtc_fast.text    PROGBITS        400c0000 02f6a8 000000 00   W  0   0  1
  [12] .defmt            PROGBITS        00000001 02f6a8 000025 00      0   0  1
  [13] .vectors          PROGBITS        40080000 012000 000400 00  AX  0   0  4
  [14] .rtc_fast.dummy   PROGBITS        3ff80000 02f6cd 000000 00   W  0   0  1
  [15] .rtc_fast.data    PROGBITS        3ff80000 02f6cd 000000 00   W  0   0  1
  [16] .rtc_fast.bss     PROGBITS        3ff80000 02f6cd 000000 00   W  0   0  1
  [17] .rtc_fast.pe[...] PROGBITS        3ff80000 02f6cd 000000 00   W  0   0  1
  [18] .rtc_slow.text    PROGBITS        50000000 02f6cd 000000 00   W  0   0  1
  [19] .rtc_slow.data    PROGBITS        50000000 02f6cd 000000 00   W  0   0  1
  [20] .rtc_slow.bss     PROGBITS        50000000 02f6cd 000000 00   W  0   0  1
  [21] .rtc_slow.pe[...] PROGBITS        50000000 02f6cd 000000 00   W  0   0  1
  [22] .stack            NOBITS          3ffd0c00 011ad4 00f400 00  WA  0   0  4
  [23] .espressif.m[...] PROGBITS        00000000 02f6cd 00001a 00   o  0   0  1
  [24] .debug_loc        PROGBITS        00000000 02f6e7 0bf5a5 00      0   0  1
  [25] .debug_abbrev     PROGBITS        00000000 0eec8c 0014ce 00      0   0  1
  [26] .debug_info       PROGBITS        00000000 0f015a 14bf41 00      0   0  1
  [27] .debug_aranges    PROGBITS        00000000 23c09b 005340 00      0   0  1
  [28] .debug_ranges     PROGBITS        00000000 2413db 02a1b0 00      0   0  1
  [29] .debug_str        PROGBITS        00000000 26b58b 17e28a 01  MS  0   0  1
  [30] .comment          PROGBITS        00000000 3e9815 00003f 01  MS  0   0  1
  [31] .debug_line       PROGBITS        00000000 3e9854 04bef5 00      0   0  1
  [32] .symtab           SYMTAB          00000000 43574c 003610 10     33 527  4
  [33] .strtab           STRTAB          00000000 438d5c 00c391 00      0   0  1
  [34] .shstrtab         STRTAB          00000000 4450ed 000184 00      0   0  1
Key to Flags:
  W (write), A (alloc), X (execute), M (merge), S (strings), I (info),
  L (link order), O (extra OS processing required), G (group), T (TLS),
  C (compressed), x (unknown), o (OS specific), E (exclude),
  D (mbind), p (processor specific)

Image saved with esp-flash version: 3.3.0

esptool.py v4.7.0
File size: 183136 (bytes)
Image version: 1
Entry point: 400809e0
8 segments

Segment 1: len 0x00100 load 0x3f400020 file_offs 0x00000018 [DROM]
Segment 2: len 0x00028 load 0x00000001 file_offs 0x00000120 [PADDING]
Segment 3: len 0x00020 load 0x3ffb0000 file_offs 0x00000150 [BYTE_ACCESSIBLE,DRAM]
Segment 4: len 0x0f51c load 0x3f400180 file_offs 0x00000178 [DROM]
Segment 5: len 0x00974 load 0x3ffb0020 file_offs 0x0000f69c [BYTE_ACCESSIBLE,DRAM]
Segment 6: len 0x1b688 load 0x400d0020 file_offs 0x00010018 [IROM]
Segment 7: len 0x00140 load 0x3ffb0994 file_offs 0x0002b6a8 [BYTE_ACCESSIBLE,DRAM]
Segment 8: len 0x0133c load 0x40080000 file_offs 0x0002b7f0 [IRAM]
Checksum: a9 (valid)
Validation Hash: e5836e0eb70abcfb1caa75129f36815ab756846cfa610d1df02968a5f9b6134c (valid)

Image saved with esp-flash version: 4.2.0

esptool.py v4.7.0
File size: 183088 (bytes)
Image version: 1
Entry point: 400809e0
7 segments

Segment 1: len 0x00100 load 0x3f400020 file_offs 0x00000018 [DROM]
Segment 2: len 0x00050 load 0x3ffb0000 file_offs 0x00000120 [BYTE_ACCESSIBLE,DRAM]
Segment 3: len 0x0f51c load 0x3f400180 file_offs 0x00000178 [DROM]
Segment 4: len 0x00974 load 0x3ffb0050 file_offs 0x0000f69c [BYTE_ACCESSIBLE,DRAM]
Segment 5: len 0x1b688 load 0x400d0020 file_offs 0x00010018 [IROM]
Segment 6: len 0x00110 load 0x3ffb09c4 file_offs 0x0002b6a8 [BYTE_ACCESSIBLE,DRAM]
Segment 7: len 0x0133c load 0x40080000 file_offs 0x0002b7c0 [IRAM]
Checksum: a9 (valid)
Validation Hash: 9b125ff9b6f27230fd50d0f565546dbb8a5c665e20628b09f84e8ab282fa0482 (valid)

[bjoernQ]

I agree with @SergioGasquez that this should be two independent issues.

On the other hand both issues seem to be caused with beta.0 ?

For the original issue (app-descriptor):

In beta.0 we haven't had the metadata section in esp-hal which makes espflash guess that it's an ESP-IDF application and show the "wrong" hint about the app descriptor:

espflash/espflash/src/image_format/idf.rs

Line 824 in b993a42

return Err(Error::AppDescriptorNotPresent(

For the problem about the two DROM sections:

We had a couple of fixes in the linker scripts after beta.0 - problems with the linker scripts can definitely cause these kind of issues. If this is reproducible with the 1.0.0 (and/or main) this would certainly be something that needs to get fixed (but in esp-hal)

I'm not really sure there is anything to do right now in espflash.

Things I can think of:

• (additionally) use some well-known symbol to guess it's an esp-hal project in

  espflash/espflash/src/image_format/idf.rs

  Line 813 in b993a42

  let is_esp_hal = object.section_by_name(".espressif.metadata").is_some();

• give a hint that the generated image will likely not boot and ask the user to report that

Not sure if the first point is really worth it tbh. The second point might be something more valuable

[DaneSlattery]

Hi, also facing this issue when using esp-idf-svc on espflash v4.2 and cargo espflash v4.2. I have esp_idf_svc::sys::esp_app_desc!(); in my code, but that doesn't inter-op.

Do we need to upstream the esp-bootloader-esp-idf into esp_idf_sys? I tried to include it directly, and faced all sorts of linker issues.

For now, I can use --ignore_app_descriptor (which, by the way, is the only flag separated by _)

[bjoernQ]

I have esp_idf_svc::sys::esp_app_desc!(); in my code, but that doesn't inter-op.

Oh that might mean we don't properly recognize it.

esp-bootloader-esp-idf shouldn't be used there - it should "just work" (but apparently doesn't)

For now, I can use --ignore_app_descriptor (which, by the way, is the only flag separated by _)

Oh that's bad UX