Troubleshooting Guide

Organized as "symptom → cause → fix", covering flashing, network, OTA, Web, and peripheral initialization issues.

1. Flashing & Boot

1.1 ESP32-C3 stuck at `boot:0x4/0x5 DOWNLOAD` after flashing

Cause: USB CDC C3 reset-sequence issue (DTR/RTS pulses leave the chip in download mode).
Fix:
1. Reset with DTR=False then pulse RTS (esptool --before default_reset --after hard_reset);
2. If that fails, physically re-plug the USB cable (most common fix);
3. Device not enumerated by Windows at all (ghost device) → try another cable/USB port.

1.2 ESP32-C6 boots with completely silent serial

Cause: peripheral config occupies GPIO16/17 (C6 UART0 console TX/RX). pinMode(16, OUTPUT) cuts serial TX — logs vanish but the device still runs.
Fix: check reserved pins in include/core/ChipConfig.h; never assign GPIO12-17/24-30 to peripherals.

1.3 ESP32-C6 panics on peripheral init

Cause: C6 exposes GPIO 0-23 only (CHIP_MAX_GPIO=23); GPIO24-30 are package-internal Flash/PSRAM SPI — configuring them panics.
Fix: keep peripheral pins within 0-23.

1.4 COM port busy, flashing fails

Cause: serial monitor, browser serial tools, or another PlatformIO process holds the port.
Fix: close all holders and retry; deploy.ps1 includes stale-process cleanup.

Cause: only firmware or only filesystem was flashed; or the locked data/www history files were used.
Fix: always flash firmware and filesystem from the same build; use the staging directory generated by deploy.ps1, never stale data/www output directly.

2. Network & Access

2.1 Device joined WiFi but IP unknown

The boot log prints the assigned IP;
STA mode supports mDNS (e.g. fastbee.local);
Check the router ARP/DHCP client table.

2.2 Correct WiFi credentials, but device only reachable at 192.168.4.1 (AP)

Cause: network.json persisted as AP mode, or stale NVS config (NVS overrides LittleFS).
Fix:
1. Newer firmware auto-corrects AP→STA at boot when staSSID is set — reboot and watch serial;
2. esptool.py erase_region 0x9000 0x5000 then reboot;
3. Offline LittleFS edit (mode=0 + staSSID), see Network Mode Switching.
Never have the ops computer join the device AP to "rescue" it — it loses internet/LAN and all further commands fail. Use serial offline recovery. :::

2.3 Web timeouts or `ERR_CONNECTION_RESET`

Check serial for reboot loops first;
Rebooting: confirm firmware and LittleFS came from the same environment, then inspect heap/maxAlloc and feature-budget messages;
Heap stable: check TCP connection budget (close extra SSE/long-lived pages).

3. OTA

3.1 OTA begin returns 501 "No OTA partition"

4MB single-app layout has no ota_1 — permanently unsupported, expected behavior. Use an 8MB/16MB layout, see Partition Layout.

3.2 OTA begin returns 503

Memory gate (free DRAM < 20KB), retryable: reduce Web load and retry; the response carries Retry-After.

3.3 Upload reports `fetch failed` / connection aborted

Most likely a false failure: the device reboots 3s after a successful write. Confirm via the arbitration chain in OTA Upgrade - False Failures.

3.4 All APIs return 401 after OTA

Reboot clears memory sessions (AuthManager is memory-only). Just log in again — expected.

4. Web UI

Optional menus are shown only when the capability is active. Check /api/features/status; if the API says inactive but the menu remains visible, update LittleFS from the same build and clear the browser cache.

4.2 Intermittent 503 "temporarily unavailable (memory pressure)"

Device is at SEVERE memory pressure; heavy endpoints are gated. Reduce concurrency, honor Retry-After, disable unused heavy features and inspect the heap/maxAlloc trend.

5. Serial Log Quick Reference

Log Fragment	Meaning
`[BOOT] Platform ready!`	Boot complete
`Mode: AP` / `Mode: STA`	Current network mode
`>>> AP fallback ...`	STA failed, fell back to AP (auto probe recovery active)
`auto-correct AP->STA`	Boot smart correction: AP switched back to STA
`ota_success` + `rst:0xc (SW_CPU)`	OTA succeeded, rebooting
`[RESTART] Reason: ...`	Planned reboot reason
`Severe web memory pressure`	Critical Web memory shortage, expect reboots/WiFi drops

Troubleshooting Guide ​

1. Flashing & Boot ​

1.1 ESP32-C3 stuck at boot:0x4/0x5 DOWNLOAD after flashing ​

1.2 ESP32-C6 boots with completely silent serial ​

1.3 ESP32-C6 panics on peripheral init ​

1.4 COM port busy, flashing fails ​

1.5 Broken pages / blank after login / auth errors after flashing ​

2. Network & Access ​

2.1 Device joined WiFi but IP unknown ​

2.2 Correct WiFi credentials, but device only reachable at 192.168.4.1 (AP) ​

2.3 Web timeouts or ERR_CONNECTION_RESET ​

3. OTA ​

3.1 OTA begin returns 501 "No OTA partition" ​

3.2 OTA begin returns 503 ​

3.3 Upload reports fetch failed / connection aborted ​

3.4 All APIs return 401 after OTA ​

4. Web UI ​

4.1 Menu item won't open / automation says "element is not visible" ​

4.2 Intermittent 503 "temporarily unavailable (memory pressure)" ​

5. Serial Log Quick Reference ​

Related ​