Addition to Troubleshooting docs (ESPTOOL-1012)

[eimermusic]

Is your feature request related to a problem?

I ran into a serial exception when uploading to an ESP32 device I am developing for. The exat same error as at the bottom of the troubleshooting guide at: https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html#a-serial-exception-error-occurred

A serial exception error occurred: read failed: [Errno 6] Device not configured

My root cause was none of the listed causes but still fairly basic one...

Describe the solution you'd like

I had bloated my build so that it exceeded the device capacity. By removing a graphic asset (as a header file) I had just added... my device was back on and happy. Might be worth adding a note about this cause to that section.

Describe alternatives you've considered

No response

Additional context

No response

[github-actions]

Hi @eimermusic! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Based on the information provided in the knowledge sources and the user's GitHub issue, I can provide the following response:

Thank you for your suggestion to improve the troubleshooting documentation. You're right that the issue you encountered is not currently listed in the troubleshooting guide for serial exceptions. The error you experienced is indeed a valuable addition to the documentation.

The current troubleshooting section for serial exceptions, as found in the ESP32 Troubleshooting Guide, focuses mainly on hardware and driver-related issues. However, your experience highlights an important software-related cause that can lead to similar symptoms.

Your suggestion to add a note about exceeding the device capacity is a great idea. It would be beneficial to include this information in the troubleshooting guide, as it could help other developers quickly identify and resolve similar issues.

I recommend submitting a pull request to the esptool GitHub repository to add this information to the documentation. You could suggest adding a bullet point like:

• The firmware image size exceeds the available flash memory on the device. Try removing large assets or reducing the code size to fit within the device's capacity.

This addition would provide valuable insight for other developers who might encounter similar issues when their builds become too large for the target device.

Thank you for taking the time to report this and suggest an improvement to the documentation. Your contribution will help make the troubleshooting process smoother for other ESP32 developers.

[Honza0297]

Hello @eimermusic and thank you for your report!
Can you please provide more information/circumstances about your application? Both ESP-IDF and esptool.py shoudl have checks to prevent loading binaries bigger than memory size.
Thank you!