Troubleshooting

Troubleshooting

Symptom	Likely cause
getFirmwareVersion() prints 0 / PN532 not found	DIP switches not SPI, or MISO/MOSI swapped
LCD shows nothing / garbled boxes	Wrong I2C address (0x27 vs 0x3F); run an I2C scanner sketch
CLI times out on every command	Wrong USB port. Use the UART-bridge one (CH34x/CP210x), not native USB. Run list-ports and pass --port
CLI can't find the device	Run python cli.py list-ports and pass --port explicitly
Upload fails	Some ESP32-S3 boards need BOOT button held during upload
users.bin resets to empty	Flash was re-partitioned. LittleFS doesn't survive partition table changes
Every card denied "No Time Sync"	No Wi-Fi configured or network unreachable at boot
Cards expire early/late	Device timezone doesn't match your timezone -- run python cli.py timezone --offset SECONDS
No buzzer sound	Must be a passive buzzer on GPIO 6
Import "Malformed JSON"	Line larger than 16KB ring buffer (batch too large), ESP32 rebooting mid-import, or debug logs on Serial polluting the protocol
Import "transfer stalled/incomplete"	Raw binary transfer (import_bin/export_bin) timed out mid-transfer -- reconnect and retry. A stall in the raw byte stream is unrecoverable without reconnecting (no framing to resync on)
Import "Duplicate UID"	Same UID appears twice in source file
"Database full (max 70000 users)"	Reached the user limit. Use --clear or reduce the file
Import rejects a name / ConvertError about UTF-8 bytes	Name exceeds 48 UTF-8 bytes (MAX_NAME_LEN) -- see Python CLI Guide
Tag-renew shows "ACCESS DENIED"	Tag is not in the device database. Add it first with cli.py add
"LOCKED - TOO MANY TRIES" on LCD	Anti-brute-force lockout after MAX_CONSECUTIVE_DENIALS denied badges in a row. Waits LOCKOUT_DURATION_MS (default 30s); serial/CLI commands still work during it
remove --force / import --clear seems slow to start	It's creating a backup first (you'll be prompted for json/bin format). Safe to let it finish