Troubleshooting

Find the cause by symptom, then follow the matching fix. Firmware-related answers are based on upstream 78/xiaozhi-esp32 v2.5.2; console operations follow the official console’s actual prompts.

By symptom

Device Connection Failures
boot → provisioning → Wi-Fi → activation → server → conversation, layer by layer
FAQ
Getting started, flashing, provisioning, audio, console and other frequent questions
Development & Debugging
Build, connection and runtime troubleshooting

Frequent scenarios

Flashing fails / won't boot
Check board type, variant, flash address and COM port
Cannot join Wi-Fi
Provisioning mode, bands and signal
Activation fails / device offline
Activation code flow and binding troubleshooting table
No sound / no wake response
Volume, microphone and speaker checks

How to troubleshoot

  1. Confirm the firmware version and board variant first: variants differ in display and networking, and mismatches are the most common cause.
  2. Then check network and server: device online state, OTA URL and server availability.
  3. Finally inspect the specific module: audio, display or peripherals per their guides.

Issues and community reports are clues; a one-off success is not a general fix — solutions require reproducible steps. Unsolved problems are welcome at [email protected].