Troubleshooting

Troubleshooting

Condensed from docs/TROUBLESHOOTING.md in the repo, which has the full detail. If none of this resolves it, open an issue with your board, firmware version, Board Mode, and the exact on-screen message.

The app won't load

"API mismatch." A firmware update moved past the Flipper API FlipDeFlock was built against (currently 87.1). Rebuild from source with ufbt — see Installation — or wait for a release targeting the new API.

Crashes or won't reopen after a flash-heavy session. The .fap loads entirely into the Flipper's ~256 KB of shared RAM. Reboot the Flipper to reclaim heap.

No detections / empty screens

"UART busy — check port." Something else already owns the serial port — usually GPS and the ESP32 configured on the same port. They need separate ones: ESP32 on USART (pins 13/14), GPS on LPUART (pins 15/16). Check Settings → ESP Port and GPS Port.

WiFi Audit / BLE Scan / Net Guardian / Locator show nothing. These four require Companion firmware and are blocked in Marauder mode, with an explicit on-screen notice. Either flash the companion firmware (ESP32 Firmware → Flash a .bin) or stick to the Marauder-compatible screens: Flock/ALPR Detect, NFC/RFID Audit, Flock Map, Reports.

Flock/ALPR Detect finds nothing. In order: check Board Mode matches your actual firmware, check the baud in Settings → ESP Baud, check TX/RX aren't swapped (the single most common wiring mistake), and confirm the ESP32 is actually powered (3V3 and GND connected). Also worth knowing: detections are deliberately conservative, so seeing fewer, better-qualified hits than expected is the intended behavior, not a bug.

GPS

No fix / no geotags. GPS is off by default — turn it on in Settings, then give the module a clear sky view. A cold outdoor start typically takes 30–90 seconds; indoors it may never lock. The app won't attach a stale fix to a detection — no current fix means the detection saves without coordinates rather than with a wrong one.

GPS works but nothing geotags. Check GPS Port and GPS Baud. NMEA sentences are checksum-verified, so a wrong baud produces silently discarded garbage, not a visible error.

ESP32 flasher

Enter the bootloader by holding BOOT, tapping RESET, then releasing BOOT.

• "VERIFY FAILED (2)" — a timeout, not a hash mismatch. Every block was already written and acknowledged; reported as "Wrote OK; MD5 n/a." Reset the ESP and test it.
• "VERIFY FAILED (4)" — a genuine MD5 mismatch (corrupted bytes in transit). Set Flash Speed to Safe and reflash.
• "Finalize failed (9)" — a cosmetic quirk of the stubless ROM path; the firmware almost certainly wrote fine. MD5 verify is the real pass/fail gate.
• "INVALID_COMMAND / software loader is resident" — a stuck flasher stub from a previous attempt. Fully power-cycle the ESP32, then re-enter the bootloader.
• "Low memory" before a flash starts. Reboot the Flipper and retry without other screens open first.

NFC

The MIFARE Classic Deep check takes minutes by design — it runs the full SD key dictionary against every sector. If the stock mf_classic_dict.nfc is missing, it falls back to a much smaller built-in list and finds less.

Reports

No report file appears. Reports only include detections you marked. Mark them, then Reports → Save Marked → Report. Files land in apps_data/flipdeflock/reports/.

Share to DeFlock

The QR won't scan / won't generate. It encodes a deflock.org deep link and renders entirely offline. A detection with no GPS fix has no coordinates to share, so turn GPS on and re-detect.