Reference

FAQ and Troubleshooting

7 min read Updated Markdown
On this page

Use this page to diagnose common release issues. Start with the check that matches the visible symptom, then record the exact message shown by WireFrame before changing project data.

Installation and startup#

WireFrame does not start or shows a blank workspace
  1. Confirm that your operating system and graphics driver meet the requirements in Installation.
  2. Restart WireFrame once without reopening an existing project.
  3. If the application opens, load the project from File → Open Project (.prjxml) or Open File and note which document triggers the issue.
  4. If it still fails, attach the operating system, WireFrame version, and startup log to the issue report.

Resetting configuration can help with a damaged workspace state, but it also removes saved session and layout preferences. Use it only after reviewing Configuration and Session.

macOS or Windows blocks the first launch

Use the operating system's Open Anyway or More info → Run anyway action only when the installer came from the official WireFrame release channel. Do not disable system security globally.

My previous project does not reopen automatically

Open it manually from File → Open Project (.prjxml) or Open File. If the files have moved or a removable drive is unavailable, WireFrame cannot restore the saved path. A normal close stores the current session for the next launch.

Projects and libraries#

Which external project formats can I import?

The project importer supports KiCad project files (.kicad_pro and legacy .pro). Altium and Eagle project import are not part of the current release workflow. Altium library files can be imported through View → Local Library Manager.

My KiCad symbols or footprints do not appear

Open View → Local Library Manager, select the source, and check that its parts are listed and ticked (a hidden part does not appear in the Library panel; Hide power & logos hides power symbols). Confirm that the source contains KiCad symbol or footprint files and has not been moved since it was added.

How do I import an Altium library?

Open View → Local Library Manager, select Add library ▾ → Altium library (SchLib, PcbLib, IntLib)..., and choose a .SchLib, .PcbLib, .IntLib, or .LibPkg file. Review the imported symbol and footprint before using it in a design. See Library Import and Management.

A component is missing from an AI-generated design

Confirm the exact part number, package, and pin count. On the card, Create searches WireFrame's published library first. Otherwise type /fix <refdes> <what is wrong> in the AI panel and attach the manufacturer datasheet with Attach datasheet...; to build every missing part at once, ask "fix the parts that cannot be used yet". Review both generated assets using Fix or Create a Component.

How do I link a footprint to a symbol?

For a placed component, select it and use Properties → General → Linked Footprint → Link Footprint & Save to File. For the library symbol, use the Library Manager's Footprint tab → Link a footprint file.... Confirm the package name, pad count, pad numbering, and orientation against the datasheet before Update Schematic to PCB. See Symbol Libraries.

Schematic and PCB#

A wire does not connect to a pin

Zoom in and place the wire endpoint on the pin connection point with grid snapping enabled. If a pin or imported symbol is off-grid, correct the symbol or its placement instead of drawing a nearly connected wire. Re-run ERC afterward.

Ratsnest lines remain after routing

Verify that each track endpoint reaches the intended pad or existing track, that all items share the same net, and that the route changes layer through a valid via. Re-run the PCB checks after correcting the connection.

DFM or DRC reports many clearance errors

Review the active design rules and net classes first. Open each violation, identify the two objects involved, and decide whether to reroute, move an item, or correct the applicable rule. Do not suppress a violation merely to obtain a clean report.

Copper zones show gaps or stale geometry

Open View → Zone Manager, confirm each zone's net, layer, clearance, and priority, then select Refill after routing or placement changes. A row at 0% has not been filled yet, or has no copper of its net to join. Clearances around objects on other nets are expected. A row marked ×2 usually means GND plane was pressed twice — delete the extra zone.

The canvas feels slow or stutters

Open View → Performance HUD. The overlay shows the frame rate on screen and the work per frame, then splits each frame into phases with mean and worst times:

Phase If it dominates
panels (CPU) — with indented rows such as pcb canvas, schematic canvas, AI copilot panel, review: BOM cards One panel is expensive to draw; the indented row names it. Closing or docking that panel is the quick test
upload + draw (GL) The graphics driver is the bottleneck — very large boards, or a weak or software GPU
platform windows (one swap each) Many panels are floating as separate windows; each costs a swap. Dock them back into the main window
swap (main window) Waiting on the display (vsync); usually not a problem in itself

The HUD also shows how many input events were queued and how far the pointer lagged behind the real cursor, and the size of the last frame's draw data. It measures only while it is open.

Simulation#

The Run button is disabled

Check the readiness information in Simulation Workbench → Setup. A run needs a usable engine, supported analysis, connected simulation scope, and no blocking model issue. Correct the reported item and run Preflight again.

WireFrame cannot find an installed simulation engine

Open Preferences → Simulation. Leave the executable path empty only when the engine is available on the system PATH; otherwise select the executable directly. Return to Setup → Engine and confirm that its status is usable.

Preflight reports a missing model

Open Models, identify the component and requested model, and import the correct vendor SPICE model. Verify its pin order against the datasheet before running Preflight again. You may also simulate an independent block that does not include the unresolved component.

An assertion is Not measured instead of Failed

The run did not produce the signal or metric needed for the comparison. Check the signal name, analysis type, circuit scope, measurement window, and engine log. Not measured is intentionally not treated as a pass.

Two engines produce different results

Compare the analysis, startup options, sources, loads, model revisions, and measurement windows. Keep both logs with the project when reporting the difference.

AI Copilot#

How do I configure AI Copilot?

Nothing to configure: sign in with a Pro or Max plan and the AI Copilot runs on WireFrame AI, paid from your plan's AI credit. Preferences → AI Assistant (or AI settings... in the Copilot menu) shows the credit left. See AI Credit and Your Data.

AI Copilot is not responding

Check the network connection, that you are signed in, the credit left in Preferences → AI Assistant, and the visible error message. Retry only after the current request has clearly stopped; repeated clicks can spend credit twice.

Does Copilot edit the design automatically?

Treat every generated proposal as unverified design input. Review its component, connection, block, and analysis tabs before applying changes. Afterward, run the relevant ERC, DFM/DRC, and simulation checks.

Copilot says a signal passes without a requirement

A pass or fail requires an explicit criterion. Add a testbench assertion based on the product requirement or datasheet and rerun the simulation. A general AI assessment is not a replacement for a measurable limit.

Export and release checks#

Fabrication output is empty or incomplete

Confirm that the board outline is closed, the selected layers contain the intended data, and the current board revision was saved before export. Inspect representative Gerbers and drill files in a viewer before sending the package to a manufacturer.

What should I review before sharing a manufacturing package?

Check the board revision, Gerber layers, plated and non-plated drill outputs where applicable, IPC-D-356A, BOM, and package manifest. Keep the DFM/DRC result with the release evidence.

Reporting an issue#

The quickest way is Help → Report a Bug... (or Help → Request a Feature...) inside WireFrame. Write a Summary and Details, optionally Attach image... (PNG or JPG; files over 10 MB may be refused), keep Include app version and OS ticked, and select Send. If sending fails, your text is kept so you can Try again later.

Whichever channel you use, include:

  • WireFrame version and operating system.
  • A short sequence that reproduces the issue.
  • The exact error message and relevant log excerpt.
  • A screenshot with credentials and proprietary data removed.
  • For slowness: a screenshot of View → Performance HUD taken while it happens. When the app cannot be clicked — or for a log over time — start WireFrame from a terminal with the environment variable WF_PERF_LOG=1; it prints a one-line timing summary every 2 seconds.
  • A minimal project copy when it is safe to share.

Check the Changelog first. Never attach API keys, customer data, or private paths.