Debug from the lowest layer upward. In embedded work, physical state and configuration mistakes often look like software problems.
App or runtime will not start
Check:
- app installed correctly,
- operating system allowed the app to run,
- disk has space,
- packaged runtime exists,
- Setup & Diagnostics shows a resolved toolchain.
In development builds, runtime resources may need to be prepared before the app can compile.
Target list is empty
Possible causes:
- managed Embedr CLI did not resolve,
- target probe failed,
- registry sync is unavailable,
- network is offline and no cache exists,
- the search query filters out all boards.
Open Setup & Diagnostics. Then try:
embedr boards --limit 10
Compile fails
Find the first real error. Then classify it.
| Symptom | Likely cause |
|---|---|
No such file or directory |
Missing library or wrong include. |
undefined reference |
Code compiled but linker cannot find implementation. |
was not declared in this scope |
Name typo, missing include, wrong framework. |
| package install errors | PlatformIO platform or dependency download problem. |
| target unknown | Wrong board id or registry target. |
Use Ask agent to fix after you have the output.
Upload fails
If compile succeeds but upload fails, check:
- correct Device selected,
- cable supports data,
- board is powered,
- USB driver installed,
- serial monitor is disconnected,
- another app is not using the port,
- correct target selected,
- bootloader mode if required.
For ESP32, try holding BOOT while upload starts.
Serial monitor shows unreadable characters
The baud rate is probably wrong. Match the monitor rate to the firmware's Serial.begin(...).
Also check:
- board reset state,
- firmware actually prints serial output,
- correct port selected,
- only one monitor connected.
Agent is confused
Give it more precise context:
- mention files with
@, - add compile output to chat,
- enable indexing,
- import datasheets,
- state target and framework,
- ask for one bounded change.
If the conversation is long, start a new chat with a concise summary.
Indexing returns bad results
Try:
- re-index the project,
- clear and rebuild the index,
- use exact search for symbols,
- avoid indexing generated folders,
- make the query more concrete.
Remember that semantic search finds meaning, not guaranteed exact matches.
Datasheet processing fails
Check:
- signed-in account,
- internet connection,
- PDF is valid,
- file is not huge or scanned-only,
- source PDF is one component rather than a catalog.
If extraction quality is poor, add a manual notes file next to the datasheet markdown.
Git operations fail
Check:
- repository initialized,
- remote URL correct,
- credentials available,
- branch has upstream,
- local branch is not behind remote.
Try git status and git fetch in Terminal. If Terminal fails too, fix Git outside the UI first.
PCB workspace is missing
Run:
embedr pcb status
embedr pcb init
If runtime is unavailable, Setup & Diagnostics or the PCB status panel should show the missing runtime details.
Best support bundle
When asking for help, include:
- operating system,
- Embedr version,
- target id,
- framework,
- selected device path,
- compile output,
- relevant source file,
- copied setup details when relevant,
- what changed immediately before the failure.