{"id":4529,"library":"esp-coredump","title":"ESP Core Dump Utility","description":"esp-coredump is a Python-based utility that aids in the post-mortem analysis of core dumps generated by Espressif chips (e.g., ESP32, ESP32-S3). It helps users retrieve and analyze the software state at the moment of an unrecoverable error, providing insights into crashed tasks, registers, and call stacks. The library is currently at version 1.16.0 and maintains an active release cadence, frequently adding support for new Espressif chips and addressing bugs.","status":"active","version":"1.16.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/esp-coredump","tags":["esp32","coredump","debugging","embedded","espressif","esp-idf"],"install":[{"cmd":"pip install esp-coredump==1.16.0","lang":"bash","label":"Latest stable release"}],"dependencies":[{"reason":"Runtime requirement","package":"python","version":">=3.7","optional":false},{"reason":"Used internally for flash operations and chip detection; often invoked as a subprocess.","package":"esptool","optional":false},{"reason":"Required for debugging (dbg_corefile) and backtrace analysis, especially when running outside the ESP-IDF environment. Must match the target chip architecture and ESP-IDF version.","package":"esp-gdb (e.g., xtensa-esp-elf-gdb)","optional":false}],"imports":[{"note":"This is the primary class for interacting with core dump functionality programmatically.","wrong":null,"symbol":"CoreDump","correct":"from esp_coredump import CoreDump"}],"quickstart":{"code":"import os\nfrom esp_coredump import CoreDump\n\n# --- This is a demonstration with dummy files. ---\n# In a real scenario, 'coredump.b64' would come from an ESP device\n# and 'program.elf' would be your firmware's ELF file with debug symbols.\n\n# Create dummy core dump and ELF files for the example to run\ndummy_coredump_b64_content = \"hDEAAAEAAAAOAAAAbAEAAA==\" # Minimal valid-looking base64\ndummy_elf_content = b\"\\x7fELF\\x02\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\" # Minimal ELF header\n\nwith open(\"dummy_coredump.b64\", \"w\") as f:\n    f.write(dummy_coredump_b64_content)\nwith open(\"dummy_program.elf\", \"wb\") as f:\n    f.write(dummy_elf_content)\n\ntry:\n    # Instantiate the CoreDump object.\n    # 'chip' must match your target Espressif chip (e.g., 'esp32', 'esp32s3', 'esp32c3').\n    # 'core' is the path to your core dump file, and 'core_format' specifies its type.\n    # 'prog' is the path to your application's ELF file containing debug symbols.\n    coredump = CoreDump(\n        chip='esp32',\n        core='./dummy_coredump.b64',\n        core_format='b64',\n        prog='./dummy_program.elf',\n        # If GDB is not in your system's PATH, specify its location:\n        # gdb=os.environ.get('ESP_GDB_PATH', None)\n    )\n\n    print(\"--- Attempting to retrieve Core Dump Info ---\")\n    # This will print information about the core dump, including task states and call stacks.\n    # With dummy files, this will likely raise an error but demonstrates API usage.\n    coredump.info_corefile()\n\n    # To start an interactive GDB debugging session:\n    # print(\"\\n--- Starting GDB session (interactive, will block) ---\")\n    # coredump.dbg_corefile()\n\nexcept Exception as e:\n    print(f\"An error occurred (expected with dummy files for full analysis): {e}\")\n\nfinally:\n    # Clean up dummy files\n    if os.path.exists(\"dummy_coredump.b64\"):\n        os.remove(\"dummy_coredump.b64\")\n    if os.path.exists(\"dummy_program.elf\"):\n        os.remove(\"dummy_program.elf\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically use `esp-coredump` to analyze a core dump file. It sets up a `CoreDump` object with dummy files for illustration and attempts to retrieve core dump information. For actual usage, replace the dummy paths with your device's core dump and application ELF files."},"warnings":[{"fix":"Install the ESP-IDF framework, or download the appropriate `esp-gdb` toolchain (matching your chip and ESP-IDF version) and add its executable directory to your system's PATH. Consult ESP-IDF documentation for specific toolchain versions.","message":"Standalone usage outside of ESP-IDF requires manual installation of the correct GDB toolchain (e.g., `xtensa-esp-elf-gdb` or `riscv-esp-elf-gdb`) and ensuring it's in your system's PATH. The GDB version must be compatible with the ESP-IDF version used to compile your firmware.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your `partitions.csv` file defines a `coredump` partition of type 'data' and subtype 'coredump' with adequate size. The required size depends on the number of tasks and stack sizes in your application.","message":"Insufficient partition size allocated for the core dump on flash can lead to 'Not enough space to save core dump!' errors during a crash. This prevents the core dump from being saved.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To analyze core dumps from encrypted flash, read them directly from the ESP device using `idf.py coredump-info -c <path-to-core-dump>` after the device decrypts and sends it. Alternatively, disable flash encryption for debugging purposes if feasible for development builds.","message":"When Flash Encryption is enabled on the ESP device, core dumps saved to an encrypted flash partition cannot be directly read using `idf.py coredump-info` or `idf.py coredump-debug` from the host. Reading must happen from the ESP, which handles decryption.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `esp-coredump` to version 1.12.0 or newer (e.g., `pip install --upgrade esp-coredump`). Version 1.12.0 includes a fix to replace `distutils` with `shutil` for Python 3.12 compatibility.","message":"Python 3.12 removed the `distutils` module. Older versions of `esp-coredump` might fail if they still rely on `distutils` for setup or internal operations.","severity":"breaking","affected_versions":"<1.12.0"},{"fix":"The ESP-IDF monitor typically handles this by automatically loading the appropriate ROM ELF files based on the target and its revision. When debugging manually, ensure that ROM ELF files are available and loaded if needed.","message":"GDB may fail to parse call stacks that involve ROM functions due to missing debug information for the ROM. This can lead to incomplete backtraces.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}