Debugging ESPHome devices: log levels, esphome logs, the debug component and web_server

1. Read the logs

esphome logs device.yaml                       # native API, then MQTT, then web_server
esphome logs device.yaml --device /dev/ttyUSB0 # serial, for boot problems before Wi-Fi is up
esphome logs device.yaml --device 192.168.1.50 # specific address when mDNS doesn't resolve

Crashes during boot only show up on serial. The network log starts once Wi-Fi and the API are up.

2. Log levels

Levels from quiet to loud: NONE, ERROR, WARN, INFO, DEBUG (default), VERBOSE, VERY_VERBOSE.

logger:
  level: DEBUG
  logs:
    sensor: INFO      # quieter for noisy components
    i2c: DEBUG

• Messages below the global level are not compiled in. To see VERBOSE output from one component, raise the global level, then quiet the others under logs:.
• Higher levels cost CPU time. Go back down after debugging, especially on ESP8266.
• baud_rate: 0 turns off UART logging, which frees the UART if you need its pins for another device.

3. Add the debug component

debug:
  update_interval: 5s

text_sensor:
  - platform: debug
    device:
      name: "Device Info"
    reset_reason:
      name: "Reset Reason"

sensor:
  - platform: debug
    free:
      name: "Heap Free"
    loop_time:
      name: "Loop Time"

• Reset reason tells you whether random restarts are brownouts, watchdog resets or crashes.
• Free heap falling over hours or days points to a leak. Largest free block / fragmentation explain allocation failures while total free heap still looks fine.
• Loop time spikes show a component blocking the main loop (long lambdas, slow sensors).

4. web_server: handy, but not everywhere

web_server: gives a local page with entities, logs and (with OTA) firmware upload. It costs a lot of memory and can reduce stability, especially on ESP8266. Keep it on trusted, segmented networks, never expose it to the internet, and set auth: (prefer the digest scheme).

Typical causes found this way