Troubleshooting
Fix Studio problems in the right order.
Start with editor errors, then project target, then flash output, then serial logs. Most failures become clear when you separate script issues from board or firmware issues.
Who this is forUsers writing scripts, saving projects, or flashing boards from Studio.
Before you startHave the project name, board chip, flash size, BLE setting, script text, and flash modal output ready.
Success meansThe script saves cleanly, flashes with the right target, and the board boots without runtime errors.
Editor, lint, and save
Syntax errorFix the Python parse error first. Indentation and missing punctuation are the common causes.
Unknown moduleOpen the docs panel. If the module is not listed, it is not supported in Studio yet.
Unknown methodUse the exact method name shown in the docs panel. Firmware may not expose every method from a native library.
Callback rejectedUse a named top-level function and follow the callback form documented for that API.
Save failsSave runs lint. Clear the visible errors and try again.
Reopened code looks strangeIf line endings or escaped characters appear, save again after the editor normalizes the text.
AI model issues
Model name not recognizedThe model must exist in the live catalog. Check spelling and use the exact model id.
More than one model loadA script can load only one model at a time. Split tests into separate projects if needed.
Model not flashedMake sure the script is saved after `cv.load("model_name")`, then start the flash flow again.
Runtime model failureCheck serial logs for memory, partition, or camera input errors. Some models require specific input shapes or camera formats.
Flashing and board target
Browser cannot see the boardUse Chrome or Edge, a data cable, and the correct USB port. Close other serial monitors.
Flash size mismatchChange the project flash size to match the physical board, then flash the matching firmware.
Firmware fetch failsThe selected chip, flash size, and BLE option must have a published firmware bundle.
Flashing stops midwayKeep the modal open, avoid disconnecting USB, and retry at a lower-risk moment if the board resets.
Board boots then errorsOpen serial logs. A successful flash only proves files were written, not that the script logic is valid at runtime.
Wrong firmware selectedOpen project settings and verify chip, flash size, and BLE option before flashing again.
Use serial logs
When a board boots but the script does not behave, serial logs are the fastest truth source. Look for module import errors, script execution errors, camera initialization failures, model loading messages, and heap or PSRAM warnings.
Import errorThe script imported a module that the flashed firmware build does not include.
Script execution errorThe runtime reached code that the linter missed or a native API rejected.
Camera failureCheck the camera preset, pins, pixel format, and power.
Model failureCheck model partition, model size, memory, and whether the script uses predict or detect correctly.
When to contact support
Send the project name, board type, flash size, BLE setting, script, visible lint errors, flash modal output, and serial logs.