{"id":23089,"library":"esp-idf-panic-decoder","title":"ESP-IDF Panic Decoder","description":"A Python tool to decode ESP-IDF panic backtraces and crash output. It translates program counter addresses to source file names, line numbers, and function names using ELF debug symbols. Current version is 1.5.0, released April 2026, with regular updates aligned with ESP-IDF release cycles.","status":"active","version":"1.5.0","language":"python","source_language":"en","source_url":"https://github.com/espressif/esp-idf-panic-decoder","tags":["esp-idf","panic-decoder","debugging","embedded"],"install":[{"cmd":"pip install esp-idf-panic-decoder","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Required for parsing panic output. Added explicitly in v1.5.0.","package":"pyparsing","optional":false}],"imports":[{"note":"The library exports a module-level function `decode_crash` and CLI entry point.","symbol":"esp_idf_panic_decoder","correct":"import esp_idf_panic_decoder"}],"quickstart":{"code":"import esp_idf_panic_decoder\nfrom esp_idf_panic_decoder import decode_crash\n\n# Path to your ELF file (with debug symbols)\nelf_path = '/path/to/firmware.elf'\n\n# Example panic output (from serial console)\npanic_output = \"\"\"0x400d1234: do_crash at /build/main.c:123\n0x400d5678: app_main at /build/main.c:45\n\"\"\"\n\ndecoded = decode_crash(panic_output, elf_path)\nprint(decoded)","lang":"python","description":"Basic usage: decode panic output using an ELF file."},"warnings":[{"fix":"Update any code that depends on target-specific register names. Use the generic register set provided.","message":"v1.5.0 removed target-specific register mapping and now uses a generic register set. If you relied on target-specific register names, your output may differ.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Check your parsing of decoded output if upgrading from <1.4.0.","message":"In v1.4.0, batch request and addr2line extraction changed the output format. Some fields may have been renamed or removed.","severity":"deprecated","affected_versions":"1.4.0 - 1.4.2"},{"fix":"Ensure your firmware build includes debug symbols (e.g., build type 'DEBUG' not 'RELEASE').","message":"The ELF file must contain debug symbols (not stripped) and must match the exact build that created the panic output.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install using 'pip install esp-idf-panic-decoder'. The import name is 'esp_idf_panic_decoder' (with underscores).","cause":"The package is installed under a different name or not installed.","error":"ImportError: No module named 'esp_idf_panic_decoder'"},{"fix":"Verify that the ELF file matches the firmware that generated the panic output. Use 'esptool.py elf2image' to check.","cause":"The ELF file does not contain the given address or is from a different build.","error":"ValueError: Could not find PC address in ELF file"},{"fix":"Remove the 'target' argument. Update code to not pass 'target'.","cause":"In v1.5.0, the 'target' parameter was removed. The function now expects only panic_output and elf_path.","error":"esp_idf_panic_decoder.decode_crash() got an unexpected keyword argument 'target'"},{"fix":"Use 'from esp_idf_panic_decoder import decode_crash' or 'import esp_idf_panic_decoder; esp_idf_panic_decoder.decode_crash()'.","cause":"The function may have been renamed in an older version or import path is wrong.","error":"AttributeError: module 'esp_idf_panic_decoder' has no attribute 'decode_crash'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}