Troubleshooting

Each entry lists what you see, why it happens, and what to do. Start with the first real error message: later errors are often consequences of it.

Install and updates

An update fails or will not install

You see an Update failed card ("The update could not be completed."), or "The update has not finished downloading."

• Click Retry on the card. If the download page opens instead, install the new version from there (Download update on manual installs).
• Restart and update warns when the agent is still working on a task, because restarting stops it. Let the run finish, or confirm to restart anyway. Otherwise the update installs the next time you quit.
• On Windows, updates install automatically and an interrupted update recovers on its own. If in-app updates never succeed on an old installation, download and install the latest version manually once; in-app updates work from then on.

Windows commands fail on paths with spaces or quotes

Commands whose paths contain spaces or quotes are passed through unchanged, and long scripts run from a file, so they are not cut off by the Windows command-line length limit. If such a command still fails, update Embedr to the latest version.

Linux: files changed outside Embedr do not show up

On large projects Linux can run out of file watches. Embedr keeps running with live updates limited instead of crashing. Raise the limit and restart Embedr:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Sign-in

Message	Cause	Fix
We could not open the sign-in window. Try again.	The browser hand-off did not start.	Try again. Google sign-in on desktop shows "Opening browser for authentication..." and finishes in the browser.
Sign-in was cancelled before it finished.	The browser tab or window was closed early.	Start again and complete the sign-in in the browser.
Please verify your email before logging in.	Email and password account not verified yet.	Open the verification email, then sign in.
This link has expired. Request a new one.	An old email link.	Request a new link.
This email is already connected to another sign-in method.	You signed up with Google (or email) before.	Use the method you signed up with.
Too many attempts. Please try again later.	Rate limit.	Wait, then try again.
Your sign-in session expired. Please sign in again to continue.	The session could not be refreshed.	Sign in again. A run that was interrupted shows "Reauthenticate to continue this run."

Models

"Model not available on your ChatGPT plan"

Your connected ChatGPT plan does not include the model you picked. Click Choose another model on the card, pick a model your plan includes, and send the request again.

If you are using Embedr's own plans and see "Your plan doesn't include this model", choose another model or upgrade. See Models.

Firmware builds

Compile fails

Open the Output panel and find the first error.

Symptom	Likely cause
No such file or directory on an include	Missing library or wrong include path.
undefined reference	The code compiled, but the linker cannot find an implementation.
was not declared in this scope	Typo, missing include, or wrong framework.
Package or platform install errors	A toolchain download failed or is incomplete.

Click Ask agent to fix in the Output panel to hand the error to the agent. See Build, upload and serial and Dependencies and libraries.

"Build timed out after 20 minutes"

The first build for a board downloads and installs its toolchain, which can be slow. The first build gets 20 minutes and later builds 10. The message ends with the last lines of the build log.

• Check your connection and build again.
• The agent explains a timeout rather than retrying the same build.
• A half-installed toolchain package is detected during the build, and the agent tells you which package is incomplete and asks before repairing it.

Arduino builds on Apple Silicon need Rosetta

You see "This board's compiler is an Intel (x86_64) build and needs Rosetta 2 on Apple Silicon, which is not installed." Some board toolchains only ship Intel binaries. Install Rosetta in Terminal, then build again:

softwareupdate --install-rosetta --agree-to-license

If the message says a toolchain program "could not run on this Mac's CPU", run a clean build first to reinstall the toolchain.

Flash fails

If the build succeeds but flashing fails:

• the Flash button says Select a device to flash when no port is selected; pick one in the device menu ("No devices detected" means the operating system sees none),
• use a USB cable that carries data, and check the board has power,
• install the USB-serial driver for your board,
• close the Serial Monitor and any other app holding the port,
• for ESP32 boards that do not enter the bootloader, hold BOOT while the upload starts.

Unreadable characters in the Serial Monitor usually mean the baud rate does not match the firmware's Serial.begin(...).

KiCad, local tools and the board

Board tools fail on Windows, or "KiCad 10 CLI was not found"

Local board operations need KiCad 10. Open Settings → Local tools:

• The KiCad row shows whether KiCad 10 is installed and if an upgrade is recommended.
• Where tools run has Local when available (use KiCad 10 or ngspice on this machine when installed, otherwise the cloud) and Always cloud.

Without KiCad 10, choose Always cloud for KiCad, or install KiCad 10. A message such as "KiCad 10 Python is required for this PCB operation" means you have an older KiCad 10; upgrade to 10.0.3 or newer. Cloud tools need you to be signed in. See Board and KiCad.

The 3D board view does not load

Message	Fix
Unable to generate a 3D preview.	Check the board opens in 2D, then reopen the 3D tab. When the 3D view is made in the cloud, make sure you are signed in.
Unable to load the generated 3D preview file.	Reopen the 3D tab.

The 3D view works without KiCad 10 installed (it uses the cloud). With KiCad 10 installed, the model is prepared in the background while you look at the 2D board, so the 3D tab opens faster.

Routing leaves open connections

The router could not complete every connection with the current placement. The board footer shows the Unrouted count, and the result keeps the best route it found.

• Move or rotate parts around the open nets to give the router room, then route again.
• Ask the agent to run automatic layout and routing (it asks for your approval first).

If you want manual routing only, say so; the agent respects it. See Placement and routing.

Manufacturing checks block the order

The footer of the Manufacturing tab tells you what blocks you:

Status	Fix
Check board to continue	Click Check board.
Board changed	The board changed since the check. Click Check again.
N DRC warnings to fix or accept	Fix the warnings, or tick each harmless one and click Accept N warnings.
KiCad DRC: N errors, Zen ERC: N errors, Provider DFM: N errors	Errors can never be accepted. Fix them; use Show on board on DFM findings to find them.
… couldn't confirm N measurements	Fix the geometry it points to and check again.
Sync the BOM to continue	Open BOM and click Sync.
Check part orientation	Review the parts in Orientation review and click I've checked these orientations.
Quote unavailable	Make sure you are signed in and online, then return to Configure.

ERC and DFM warnings cannot be accepted either. See Manufacturing and ordering.

Simulation

Message	Cause	Fix
<file> has no Simulation() setup	The .zen file has no simulation bench.	Ask the agent to add a Simulation with a stimulus and control block.
The SPICE simulation failed; see the ngspice output.	The circuit or the control block failed, or an assertion stopped it.	Read the ngspice output in the tool row; ask the agent to fix the bench.
ngspice is not installed … and the simulation worker needs a signed-in session.	No local ngspice and not signed in.	Sign in, or install ngspice (brew install ngspice on macOS, sudo apt install ngspice on Linux; on Windows download it from ngspice.sourceforge.io).
Simulations are set to run in the cloud (Settings → Local tools), and the simulation worker needs a signed-in session.	Cloud chosen while signed out.	Sign in, or switch SPICE to Local when available.

See Simulation.

Sharing

Message	Fix
Shared projects are limited to 500 files; this project has N.	Leave generated or bulky folders out with .gitignore, then publish again.
Shared projects are limited to 100 MB; this project has N MB.	Same: exclude large outputs, archives and media.
<path> is larger than the 25 MB per-file limit for shared projects.	Exclude or shrink that file.
A file you expected is missing	Check the Left out list in the share preview: files can be left out as generated, as looking secret, by .gitignore, or as a link.

People opening an invite-only project see one of these:

Page	Fix
Sign in to view <project>	Sign in with the email address the project was shared with.
You don't have access to this project	They are signed in with a different address. Click Sign in with a different account, or ask the owner to invite that address.
Your email address isn't verified yet	Verify the email, then open the link again.
Project not found	The project is private, unpublished or the link is wrong.

See Sharing projects.

Git

"The repository needs you to sign in"

The remote refused the request without credentials (Embedr never opens a terminal prompt). In the Git menu, enter an Access token (and Username (if your host needs it)), optionally tick Remember for <host> on this computer, and click Try again. A remembered token is encrypted with your system keychain. For SSH remotes, fix your SSH key setup outside Embedr; the message starts "The server refused the connection".

A merge or pull stopped on conflicts

The Git menu shows Merge in progress and the conflicted files. For each file keep one side, or edit it and mark it Resolved, or click Resolve with agent. Then Complete merge, or Abort merge to go back. Files that still contain conflict markers cannot be marked resolved.

See Version control.

Agent runs

Symptom	Cause	Fix
The window reloaded mid-run	Runs continue in the background.	Reopen the thread; it picks up the run's progress.
"Compacting context…" then "Context automatically compacted"	The conversation filled the model's context, so earlier turns were summarized.	Nothing; the agent continues. For a new topic, start a new chat.
"This draft (~N tokens) won't fit; remove attachments or start a new chat."	The message plus attachments is too large.	Remove attachments, attach fewer files, or start a new chat.
"Waiting for a worker…" (browser)	The cloud run has not started yet.	Wait; after 90 seconds it reads "Still waiting for a worker…". A run that never starts is retried or ended with an error automatically.
"Waiting for you"	The agent is waiting on an approval or question.	Answer the card in the chat.
A helper "was stopped" or "failed"	A helper thread ended early.	Open the helper's thread to see why; ask the agent to retry.
The agent drifts	Too little context.	Mention files with @, paste the exact error, state the target, and ask for one bounded change.

A message you send while a run is working joins the run before its next step ("Joins next step") instead of cancelling it. See Embedr agent.

Contacting support

Email support@embedr.app with:

• your operating system and the Embedr Version from Settings → About,
• desktop app or browser,
• the target and framework, or the board file, involved,
• the exact error text (use Copy in the Output panel),
• the model selected in chat, for agent issues,
• what you changed just before it started failing, and whether it happens again after a restart.