Start with the symptom below. Record your product, version, operating system, and the exact error. Trace desktop, Trace Plugin, and the CLIs have different recovery paths.
Installation Issues
macOS: "Trace is damaged and can't be opened"
Use the official download page and check that the installer matches your system. If a fresh download is still rejected, stop and contact support with the version and warning.
Do not remove quarantine attributes or disable Gatekeeper to make an unverified download run.
macOS: "Trace can't be opened because Apple cannot check it for malicious software"
Check the download's origin and publisher before proceeding. Do not assume the warning is harmless because an older guide says it was fixed. Follow your organization's security policy and ask support to verify the installer.
Windows: SmartScreen warning
Check that the installer came from the official download route and inspect its publisher/signature information. If Windows blocks it or the publisher is unexpected, do not use a blanket "Run anyway" workaround. Send the warning and installer version to support.
Linux: AppImage won't run
Check that the official download matches your architecture and distribution support. For a verified AppImage, use your file manager's permissions to allow execution, then launch it.
If it still fails, capture the terminal error and the distribution/version. Do not substitute extraction or runtime flags from another release without checking its instructions. See Installation.
Linux: Authentication fails or doesn't persist
Check that your desktop's credential service is available and unlocked. Follow your distribution's guidance for configuring its keyring service. If login still fails, report whether browser sign-in completed and what Trace displayed afterward.
Linux: Wayland display issues
Record the desktop environment, display session, GPU, and driver version. If your system already supports an X11 session, checking the same project there can help isolate a display problem. Do not change system drivers or security settings solely on the basis of this guide.
Performance Issues
Trace is running slowly
Check whether a specific view, library search, AI task, or layout job is slow. Close an unused 3D view and other resource-intensive applications, then compare the same small project.
For a persistent slowdown, record the project size, affected action, and whether it happens before or after an online task starts. Contact support with a small reproduction; changing circuit structure or relaxing design rules is not a performance fix.
Project Issues
Project won't open
For a native project, check for the .kicad_pro project file and the .trace_sch or .trace_pcb design files, with their paired .xo files. Keep the whole project and its libraries together.
For a local design, follow Opening projects. For a cloud project, use Workspaces rather than bypassing its access or recovery checks.
If Add finished in the cloud but Open failed locally, inspect that existing project's status. Do not create a second copy to solve the opening failure.
Missing libraries or footprints
Check the affected symbol or footprint's library identifier, project library tables, and referenced files. Restore dependencies from a trusted library source or assign the correct verified part.
A placeholder rectangle is not proof that pins or connectivity are correct. Compare the actual pin numbers, electrical types, nets, and footprint pads with the part's datasheet before continuing. See Components.
Schematic and PCB out of sync
Review schematic annotation, footprint assignments, and the intended changes before using Update PCB from Schematic. Save intended work first, review the update, then check the board and DRC.
An update can change more than the component you were looking at. It is not a substitute for checking pin-to-pad assignments.
"Update PCB from Schematic" stuck on processing
Check the tool's error or progress output before assuming the cause. Missing footprint assignments are one possible issue; unresolved libraries or a failed save can also need attention.
If the outcome is unclear, inspect the live board and saved files before repeating the update. Include the error and whether any changes appeared when contacting support.
AI Assistant Issues
"My changes disappeared between sessions"
Native .trace_sch and .trace_pcb files store the saved design. Their paired .xo files carry additional drawing and board data; keep both when backing up or recovering a project.
- Confirm that the same project and branch are open.
- Check chat for a failed edit, save, or reload.
- Compare the saved files with the editor and available Local History.
- Preserve the project before choosing a restore or reload.
Do not ask the assistant to reapply an uncertain edit or save an older editor buffer over newer disk changes. If you cannot establish which version is current, contact support.
"AI shows empty rectangles instead of my components"
Treat this as a library-resolution problem until the actual symbol has been inspected. Follow Missing libraries or footprints; do not assume only the graphics are affected.
"The conversation is getting very long — will the AI lose track?"
Long conversations can be summarized, and details can be lost. Restate important constraints, verify the current design, and keep confirmed requirements in the appropriate project notes.
Use focused requests for large projects. Do not start a replacement request while an earlier operation's outcome is unknown.
AI access or model selection is unavailable
Check the signed-in account, Billing, and the open project's permissions. If the picker says Choose model, select a supported choice.
Compatible builds offer GPT Astra, GPT Sol, Trace Genie 2.0 Flash, and Trace Genie 2.0. An older saved choice may not be supported by your current service. See Models and Availability.
"Autoroute is taking forever / timed out"
Review the selected engine, job type, time budget, and preflight findings. A dense board may produce incomplete routing within the budget. Check the actual result and charge rather than assuming the timeout means no work or no billing.
Preserve fixed placements and valid rules. Do not weaken constraints simply to get a completed status, and do not assume a whole-board engine can be restricted to one net or area. See Placement and routing.
Network Issues
Can't connect to Trace services
Check your connection and the status page. On a managed network, ask your administrator whether Trace's service is permitted; do not disable required protections.
An Operational status does not rule out an account-, feature-, or region-specific service issue. Capture the exact error and time.
Connection dropped during an AI response
Wait for Trace's reconnect or recovery state. If it offers Resume for the existing task, use that control instead of submitting the original prompt again. A terminal task error is not the same as a dropped connection.
If delivery or an edit's outcome is unknown, inspect the original operation and saved design before taking another action. Stop does not roll back edits or guarantee that all work is unbilled. See Chat controls.
Cloud save, Pull, or branch switch did not finish
Read the specific Workspaces status. Cloud publication, local application, and opening an editor are separate outcomes.
Keep recovery files and use the controls for the original operation. Do not create a duplicate project, repeat a publish, or discard local changes to clear an uncertain state. See Workspaces.
Export Issues
Gerber files rejected by manufacturer
Compare the generated files with the manufacturer's requirements: outline, layer mapping, units, drills, and any required assembly files. Reopen the outputs in a viewer and check the selected variant.
Run applicable board checks, but do not treat a DRC pass as acceptance by the manufacturer. See Exporting.
BOM export missing components
Check references, values, inclusion/DNP settings, the active variant, and the export's filters. Verify the output against the intended assembly rather than adding parts just to make the counts match.
Graphics Issues
"Graphics error: Unknown incomplete framebuffer error id 8219"
Record the warning, product version, GPU, and affected view. If a canvas is blank or incorrect, do not assume it is safe to ignore or that the design is empty.
Preserve unsaved work before restarting. Report persistent errors, including the view or tab transition that triggers them. The older issue link is graphics issue.
Display glitches after sleep/wake
Check whether the problem affects a canvas, a 3D view, or chat. Preserve unsaved edits before closing a document or restarting Trace. If the saved design and screen disagree, avoid overwriting either version until the mismatch is understood.
Auto-Updater
Follow the update instructions offered for your product and platform. An update notification may lead to a download rather than an in-place installation.
Keep a project backup and verify the running version afterward. Do not remove an older installation or its data merely because a previous guide promised automatic migration.
Trace Plugin connection issues
Check that the intended host project is open and the plugin shows the correct document and connection. For KiCad, follow its API and platform-permission setup in the KiCad guide; for Altium, follow the Altium guide.
Host save, reload, and undo behavior differs from native Trace. If the plugin edited disk while the host still shows an older buffer, do not save that stale buffer over the edit. Follow the host guide's reload procedure or contact support.
Found a Bug?
Email hello@buildwithtrace.com, use GitHub Issues where available, or ask in Discord. Include:
- Product and version; host editor/version if using Trace Plugin.
- Operating system and architecture.
- Short reproduction steps and expected versus actual behavior.
- Exact safe error text and approximate time.
- Whether the issue changed saved files or left an operation uncertain.
Redact credentials, sign-in links, payment details, private paths, and design content you cannot share. Check logs and crash reports before sending them; do not assume they contain no sensitive information. A small, non-confidential reproduction is preferable to your full project.
Still Having Issues?
Contact support@buildwithtrace.com or hello@buildwithtrace.com with the details above. For a workflow improvement rather than a bug, see Feature requests.