> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to resolve them.

## Installation Issues

### macOS: "Trace is damaged and can't be opened"

<Info>
  **Fixed in v1.2+** — This issue has been resolved. Trace is now properly signed and notarized for macOS, including Sequoia (15+). If you're on v1.2 or later, you should not see this. If you're on an older version, update to the latest from [buildwithtrace.com/download](https://buildwithtrace.com/download).
</Info>

If you're still on an older version and see this error, macOS has quarantined the app. To fix:

<Steps>
  <Step title="Open Terminal">
    Launch Terminal from Applications → Utilities.
  </Step>

  <Step title="Run the fix command">
    ```bash theme={null}
    xattr -cr /Applications/Trace.app
    ```
  </Step>

  <Step title="Reopen Trace">
    Try opening Trace again — the warning should be gone.
  </Step>
</Steps>

### macOS: "Trace can't be opened because Apple cannot check it for malicious software"

<Info>
  **Fixed in v1.2+** — This is resolved in the latest version. All binaries now use relative paths, the CLI is properly named, and `Info.plist` metadata passes Gatekeeper validation. Update to the latest version to avoid this entirely.
</Info>

If you're on an older version: go to **System Settings → Privacy & Security**, scroll down and click **"Open Anyway"** next to the Trace message.

### Windows: SmartScreen warning

Click **"More info"** then **"Run anyway"**. This warning appears because Trace is new and hasn't built up reputation with Microsoft yet.

### Linux: AppImage won't run

If double-clicking the AppImage does nothing, make sure it's executable:

```bash theme={null}
chmod +x trace-*-linux-x86_64.AppImage
```

Trace's AppImage uses a modern DwarFS-based runtime (uruntime) that does **not** require FUSE. If the AppImage still won't start, try extracting and running directly:

```bash theme={null}
URUNTIME_EXTRACT=1 ./trace-*-linux-x86_64.AppImage --appimage-extract
./squashfs-root/AppRun
```

### Linux: Authentication fails or doesn't persist

Trace uses `libsecret` (GNOME Keyring / KDE Wallet) to store credentials. If you're on a minimal desktop or a window manager without a secret service:

1. Install a secret service provider: `sudo apt install gnome-keyring` or `sudo apt install keepassxc`
2. Ensure D-Bus is running: `dbus-launch --exit-with-session`
3. If credentials still don't persist, install the runtime library: `sudo apt install libsecret-1-0` (Ubuntu/Debian) or `sudo dnf install libsecret` (Fedora)

### Linux: Wayland display issues

Trace uses GTK3 with WebKit2GTK. On Wayland compositors, if you experience rendering glitches or the chat panel doesn't display correctly:

1. Try running with X11 backend: `GDK_BACKEND=x11 ./trace-*-linux-x86_64.AppImage`
2. If using NVIDIA + Wayland, ensure you have the latest proprietary drivers installed
3. EGL canvas support is available on wxWidgets 3.3.2+ (experimental)

## Performance Issues

### Trace is running slowly

* Close other resource-intensive applications
* Ensure you have at least 4GB of free RAM
* For large designs, consider splitting into hierarchical sheets
* Disable 3D view when not needed

### High CPU usage during idle

This can happen if auto-save is running frequently. Go to **Preferences → General** and increase the auto-save interval.

### First launch is slow while libraries load

On first launch, Trace indexes its stock symbol and footprint libraries (tens of thousands of parts). This runs in the background at low CPU and I/O priority, so the app and the rest of your machine stay responsive while it works — on lower-spec machines (8 GB RAM) it may take a few minutes to finish, and library search results fill in as indexing completes. Subsequent launches are fast.

## Project Issues

### Project won't open

* Check if the project file (`.trace_pro`) exists and isn't corrupted
* Try opening the schematic (`.trace_sch`) or PCB (`.trace_pcb`) file directly
* Check for backup files in the project directory

### Missing libraries or footprints

If components show as missing:

1. Go to **Preferences → Manage Symbol Libraries / Footprint Libraries**
2. Verify the library paths are correct
3. Re-add any missing libraries from the Trace library collection

### Schematic and PCB out of sync

Run **Tools → Update PCB from Schematic** to synchronize changes. If issues persist, check the annotation and footprint assignments in the schematic.

### "Update PCB from Schematic" stuck on processing

If the update appears to hang or stays on "processing" indefinitely, the most likely cause is one or more schematic symbols without a footprint assigned.

1. Go back to the **Schematic Editor**
2. Click on each symbol and check the **Footprint** field in the properties panel
3. Any symbol with a blank or missing footprint will block the update
4. Assign the correct footprint, then retry **Tools → Update PCB from Schematic**

<Tip>
  You can quickly find unassigned footprints by running **Tools → Edit Symbol Fields** and sorting by the Footprint column. Any empty cells need to be filled.
</Tip>

## Export Issues

### Gerber files rejected by manufacturer

* Verify you're using the correct layer mapping for your manufacturer
* Check that drill files are included and in the correct format (Excellon)
* Ensure board outline is on the Edge.Cuts layer
* Verify units match manufacturer requirements (usually mm)

### BOM export missing components

Components need proper values and footprints assigned. Check that all components have:

* A reference designator (R1, C1, U1, etc.)
* A value field populated
* A footprint assigned

## Network Issues

### Can't connect to Trace services

* Check your internet connection
* Verify firewall isn't blocking Trace
* Try disabling VPN if you're using one
* Check [status.buildwithtrace.com](https://status.buildwithtrace.com) for service status

### Connection dropped during an AI response

If your network drops while the AI is responding, the response is not lost. The AI keeps working server-side, and Trace automatically reconnects and continues streaming from where it left off. If automatic reconnection doesn't succeed, a **Resume** banner appears in the chat — click it to pick the same response back up without re-running your prompt.

If you click **Stop** instead, generation is halted on the server too, so you aren't billed for output you didn't want.

## Windows Installer & Upgrades

### In-Place Upgrades

Starting with Trace 1.2, the Windows installer performs in-place upgrades instead of side-by-side installations. When you install a new version:

* The installer detects your existing Trace installation and upgrades it in place
* Your settings, projects, and local history are preserved
* Old versioned installations (1.0.0, 1.1.0, 1.2.0, 1.2.1) are automatically detected and silently removed
* Registry keys, shortcuts, and file associations are updated to the new version

If you're upgrading from a pre-1.2 version that installed as a separate application (e.g., `C:\Program Files\Trace\1.1.0`), the installer removes the old versioned installation before installing the new version.

## Auto-Updater

Trace checks for updates automatically on launch. When a new version is available:

1. A notification appears in the application
2. Click to download and install the update
3. The update installs over your current version (in-place upgrade)

The auto-updater detects your platform (`macos`, `windows`, or `linux`) and architecture (`x86_64`, `aarch64`, or `universal`) automatically. You can also check manually from **Help → Check for Updates**.

## Crash Reporting

If Trace crashes during a session, the next launch shows a dialog asking whether you'd like to send a crash report. This is consent-based — the report is only uploaded if you click **Send**.

The dialog only appears for confirmed crashes. Ordinary unclean shutdowns — a force-quit, an OS shutdown, or a power loss — no longer trigger the prompt.

Crash reports include the application log from the previous session. They do not include your design files, personal information, or project contents. Reports help the team diagnose and fix stability issues.

## Configurable Backend URL

If you need to connect to a different backend (e.g., a staging or self-hosted instance), you can change the backend URL from any editor:

1. Go to the Trace settings panel (accessible from the menu in any editor)
2. Enter the new backend URL
3. Restart the application for the change to take effect

<Note>
  The default backend URL (`api.buildwithtrace.com`) is compiled into the application. Changing it via settings overrides the compiled default. This is primarily useful for development and testing.
</Note>

## Graphics Issues

### "Graphics error: Unknown incomplete framebuffer error id 8219"

This error can appear when opening Trace or switching to certain views (3D viewer, PCB editor). It's related to OpenGL framebuffer initialization on macOS, which has deprecated OpenGL in favor of Metal.

**You can safely click OK and continue working.** The application will function normally after dismissing the dialog. If the error appears frequently, try:

* Updating to the latest version of macOS
* Closing other GPU-intensive applications
* Checking for graphics driver updates

This is a [known issue](https://github.com/buildwithtrace/trace/issues/9) we're working on resolving.

### Display glitches after sleep/wake (macOS/Linux)

If the PCB or schematic editor shows rendering artifacts after waking your machine from sleep, the OpenGL context may have been lost. Trace automatically recovers the OpenGL context on wake, but if artifacts persist:

* Close and reopen the affected editor tab
* If that doesn't help, restart Trace

## Footprint and Library Issues

### Footprint loading warning

You may see a warning about footprint resolution when loading a design. This happens because KiCad and Trace use separate systems for resolving footprint libraries. **This warning is safe to ignore.** Your footprints are loaded and working correctly through Trace's own library system.

If footprints are actually missing from your design, see [Missing libraries or footprints](#missing-libraries-or-footprints) above.

## AI Chat Tips

### Use plan mode before complex edits

For best results, use **plan mode** before asking the AI to make significant changes to your design. Plan mode lets the AI:

* Ask clarifying questions about your intent
* Research components and reference designs
* Outline an approach before modifying any files

This prevents wasted edits and ensures the AI fully understands what you want before touching your schematic or PCB. You can enable plan mode by typing "plan" or selecting it from the mode selector in the chat panel.

## AI Assistant Issues

### "My changes disappeared between sessions"

The AI writes to intermediate `.trace_sch`/`.trace_pcb` files which are then converted to KiCad format. If the conversion fails, your changes exist in the trace file but aren't visible in the editor — a warning appears in the AI chat when this happens.

**Fix:**

1. After the AI makes edits, save explicitly (**File > Save** or Ctrl+S)
2. Check the AI chat panel for any conversion warnings (yellow text)
3. If changes vanished, try asking the AI to "re-apply the last edit" — it can often recover

### "AI shows empty rectangles instead of my components"

This means the symbol library couldn't be resolved. The electrical connections (wires/nets) are correct — only the graphical representation is missing.

**Fix:**

1. Go to **Preferences > Manage Symbol Libraries**
2. Verify that the global library table includes the standard KiCad libraries
3. Check that `KICAD9_SYMBOL_DIR` points to a valid directory
4. Restart Trace after fixing library paths

### "The conversation is getting very long — will the AI lose track?"

Long conversations are condensed automatically: older messages are summarized in the background while hard requirements you stated (board dimensions, part choices, constraints) are preserved verbatim. The context meter in the chat panel shows how much capacity the current conversation tab has used — each tab has its own meter.

If the AI does start losing nuance in an extremely long session, start a fresh conversation and copy your current requirements into the first message. For complex projects, working on one subsystem per conversation still gives the best results.

### "Autoroute is taking forever / timed out"

Cloud autorouting has timeout limits for dense boards. Boards with 200+ nets and tight spacing may not complete within the allowed time.

**Fix:**

1. Route critical nets manually first (power rails, high-speed differential pairs)
2. Increase board area if possible — more space gives the router more options
3. Reduce via count constraints if your design rules allow
4. Try routing in stages: route one area, then ask the AI to route the rest

## Found a Bug?

If you run into a bug, please open an issue on our [GitHub Issues page](https://github.com/buildwithtrace/trace/issues) so we can track and fix it. Include as much detail as possible:

* Trace version (Help → About)
* Your operating system and version
* Steps to reproduce the issue
* Any error messages or screenshots

Bug reports help us improve Trace for everyone.

## Still Having Issues?

If you can't find a solution here:

* Check our [Discord community](https://discord.gg/UNUvQxneCr) for help from other users
* Email us at [hello@buildwithtrace.com](mailto:hello@buildwithtrace.com) with details about your issue