Troubleshooting by symptom
Find the line that matches what you see. Messages are quoted as the app shows them, so you can search this page for the words on your screen.
14.1Nothing happens, or every reading is 0 V
First check. First look at the status bar: Live MNA · WASM · running, · paused or · halted. Only a halt is also shown on the canvas.
| What you see | Why | What to do |
|---|---|---|
| Every voltage reads 0 V and the status bar says paused | The live simulation is paused. | Press Ctrl+R. The colours and readings start to move. |
| Every voltage reads 0 V and the status bar says running | The circuit has no source, or the source isn't wired in. | Place a source (V for DC, A for a sine) and wire both of its pins. |
| A wire ends in a pair of net labels instead of a line | Every route between its two ends would have run through another pin. | Nothing is wrong: the labels join the two ends. Move a part to make room and draw the wire again if you want a line. |
| Wires stay grey after you drew them | The wire ends aren't on pins, so nothing is connected. | Wires join only at their ends and at pins. Drag from pin to pin, or use the Wire tool (W) and click the pins. |
| An empty sheet with a start hint, and idle in the status bar | There's nothing to run yet. | Place parts, or click Open an example or Import in the hint. The live simulation starts on the parts by itself. |
| The scope shows one line, "No probes yet. Select a part and press Add to scope, drag a trace name here, or", and a Probe tool (P) button | Nothing is probed. | Click Probe tool (P), or press P and click a net, or select a part and click Add to scope (Probe a signal and read it on the scope). |
| The scope shows a blur or a solid band | The window holds hundreds of cycles of the signal. | Zoom the scope in with the wheel while it runs: it samples faster and shows each cycle. Or press 1 (1 ms/s) or 2, or type a slower timebase in the toolbar. |
| An analysis key (F7, F8, Shift+F7…) opens the setup instead of running | The circuit has no saved setup for that analysis yet. | Click Run in the setup. It's saved, and the key runs the analysis from then on. F6 opens the setup again. |
| In Split view, clicking the schematic selects a part instead of adding a trace | A plain click edits, as in the Schematic view. | Hold Alt and click the net or part to add its trace. |
| Esc didn't close the dialog | In a dialog field, the first Esc cancels that field's edit. | Press Esc again. |
| A key does nothing | A text field, a slider or a dialog has the focus. | Ctrl combinations and F-keys work everywhere. For a single-letter key, press Esc or click the canvas first. A focused slider keeps its arrow keys, a tick box its Space. |
| Probing a net adds nothing: "… already shows this net" | The net or current is already probed. | Nothing to fix. The existing probe is selected and flashes. |
14.2Red Halted, a red badge, or a diagnostic code
First check. First press Alt+6: the Diagnostics tab names the part, the net and the fix. Click the row to zoom to it.
| What you see | Why | What to do |
|---|---|---|
| Red Halted button and Halted · code pill | The live simulation can't continue. | Click the button. Fix what the diagnostic says. The simulation restarts by itself. |
E_NO_GROUND: "The circuit has no ground." | No 0 V reference. | Click Add ground in the Diagnostics row, or place a ground (G) and wire it to the 0 V side of the circuit. |
E_FLOATING_NET: "Net … has no DC path to ground." | A net joins only through capacitors or open gates, so nothing sets its voltage. | Click Add 1 GΩ to ground in the Diagnostics row, or add a resistor from the net to ground yourself, or connect the net. The badge clears. |
W_ISO_TIED: "Isolated ground ISO1 is joined to the main ground", and an amber tag ISO1 tied to GND on the canvas | A wire, label or main ground symbol sits on the isolated side, so the two grounds are one net. | Click Show the tie in the Diagnostics row to select the joining wires and labels, then delete them. Or click Make it the main ground if the two sides are meant to be one. |
E_VSRC_LOOP | Two voltage sources, or a source and an inductor, in parallel. | Add a small series resistance (1 mΩ), or give the inductor a small dcr. |
E_VSRC_SHORT: "V1 is shorted" | A wire joins both pins of a source. | Delete that wire. |
E_NEWTON or E_TIMESTEP (didn't converge) | The solver could not find a solution at that instant, often at a hard switching edge. | The message names the part. Add series resistance, slow the edges of sources, or lower max step. In Simulate, try the Gear method (Transient). |
E_PARAM: "R1 parameter r = 0 is out of range" | A value outside what the part accepts. | Type a value inside the range the message gives. For a link, use a wire, not 0 Ω. |
W_PARAM: "V2: rise … + width … + fall … is longer than the period …" | A pulse source whose edges and width don't fit in its period, so each pulse is cut off when the next period starts. | Do what the message says: make the width at most period − rise − fall, or the period at least their sum (Pulse source). |
| A red line under a field, "abc" is not a value: try 4k7, 10u, 1meg, and a message "… kept …" | The text isn't a number the part can take: not a number, zero for a resistance, or a negative delay. | Type a plain number or an SI prefix: 4k7, 100n, 1Meg. A comma decimal (1,5) is refused. The line says what the field needs. |
W_NO_MODEL: "X3 has no model: assign one." | An IC box or vendor part with no model. | Double-click the part and choose a model (Choose the model a part uses). A blank Subcircuit / IC can instead be built: double-click it (Editing a subcircuit). |
W_MCU_PIN: "U1 pin BTN floats … so it reads random values" | An MCU input that nothing drives rests at half the supply. | Write pin BTN in pullup in the code, or wire a 10 kΩ resistor to VDD or GND (GPIO: outputs and inputs). |
W_MCU_PIN: "pin LED sources 40 mA (an MCU pin is rated about 25 mA)" | The pin drives more than its limit, or two outputs are joined. | Add a series resistor (330 Ω for an LED) or drive the load through a transistor. |
W_MCU_BUS: "SDA … has no pull-up resistor, so the transfer fails", and OLED.ack is 0 | I²C lines are open-drain and go high only through pull-ups. | Add 2.2 kΩ to 10 kΩ from SDA and from SCL to VDD (I²C). |
W_MCU_BUS: "no target answered (NACK)" | The 7-bit address is wrong, or the target isn't powered or not wired. | Check the address in the datasheet (0x3C for an SSD1306), the target’s supply and the wiring. |
W_UART: "framing error on RXD (the stop bit is low) …", and the text from the MCU is missing or wrong in the Console | A USB-UART bridge received a frame at another baud rate than its own, so the byte is dropped, or its RXD is wired to something that's not a UART signal. | Set the bridge’s baud to the rate in the MCU’s bus … uart line, and wire the bridge’s RXD to the MCU’s TX (Chips and displays). |
| The Console has no input bar, or text typed there goes nowhere, or an error line follows the → text line | The bar belongs to a USB-UART bridge. Without a bridge in the circuit there's nothing to send through. Text also needs the live simulation to have started, with the bridge powered above 2.5 V. | Place a chip of variant usb_uart, wire its TXD to the MCU’s RX and its RXD to the MCU’s TX, power its VCC, and press Play (Console). |
| An MCU line is marked red in the code box, and the chip doesn't run | The program has a mistake, E_SCRIPT. | Read the status line under the code: it names the line and says what to write, for example wait 10ms instead of wait 10 (Errors in the code). |
| The MCU has no pin I declared | The code has an error above that line, or the name is a supply pin, or the program is the old script API (fn step()). | Fix the error shown under the code. Declare I/O pins with other names than VDD and GND. |
A small open dot on a pin, E_UNCONNECTED_PIN | A pin with nothing on it, shown 1.5 s after your last edit. It's a warning. | Wire the pin, or leave it if it's meant to be open. Wire it and Delete in the Diagnostics row do it in one step. |
14.3The result looks wrong
First check. First ask which result you're reading: the live simulation or a Simulate run (When to trust which result).
| What you see | Why | What to do |
|---|---|---|
| Live and Simulate disagree on an op-amp or regulator | The live simulation runs a model fitted to the vendor's. Simulate runs the vendor file. | Trust Simulate for numbers at the edges (clipping, rails, start-up). |
| An op-amp output stops short of the rail | The vendor model limits the swing, sometimes more than the datasheet. | Check against the datasheet. A model isn't the part. |
| Ripple or overshoot looks smooth or too small in Simulate | max step is too large for the fastest edge. | Set max step to a tenth of the shortest rise time and run again. |
| A capacitor starts charged, or a run skips the start-up | A part sets ic, or the circuit sets uic. | Check the Transient tab and the circuit settings (Settings saved in the circuit). |
| The live simulation starts with every capacitor empty, but I expected the settled state | A circuit made with File → New starts at rest. | Untick (Start a circuit from rest or from the operating point). Examples and older files start settled. |
| An example shows the output settled from the first instant, with no start-up | Examples start from the DC operating point. | Tick to see the power-on. |
| A probe on an isolated side reads a different voltage from the parts beside it: "… (vs GND)" | It was made with Shift+click, which measures against the main ground, so it includes the float of the isolated side. | Remove it and probe again with a plain click ("… (ISO2)", against that side's ground). |
| A reading shows 0 and its tooltip gives a tiny number such as −2.3 fV (solver residue) | A value below a billionth of the circuit's own scale is solver noise and is shown as 0. | Nothing. The exact value is in the tooltip, and CSV and Copy keep the raw numbers. |
| An analysis tab says No FFT result yet (or another analysis name) with a Run button | Each analysis tab keeps its own result and this one hasn't been run. | Click Run. The other tabs keep their results. |
| A chip Circuit edited since this run above the result | Parts or wires changed after the run, so the plot may no longer match the circuit. | Run the analysis again (Ctrl+F5). |
| A warning that Simulate ran again from 0 V | ngspice found no DC operating point, common for some vendor op-amp models. | Nothing. The run starts from power-up, with every capacitor discharged. |
| The plot says a trace could not be read: "this run has no signal for it" | The signal isn't in this result, for example the AC current of a part that has none. | Probe a nearby net or part instead. |
| The Bode plot has no margins in the strip | The output trace never crosses 0 dB or −180°. | Margins exist only for a loop gain. Probe the loop, not the closed-loop output. |
| The FFT shows nothing, or asks for a longer stop time | Use data from is past the end of the transient. | Make the Transient stop time longer, or Use data from smaller (FFT). |
| Run is greyed and "Must be earlier than the stop time…" under Start saving at | Nothing would be kept. | Set Start saving at below the stop time. |
| A DC sweep note: "All signals skipped… only the probes were kept" | The sweep was too long to keep every signal. | Probe the signals you need before the run. |
14.4Slow, stuck or busy
First check. First look at the Simulate button: while a run is going it shows the percentage, the seconds and Cancel.
| What you see | Why | What to do |
|---|---|---|
| The status bar says Live MNA · JS | A part isn't in the fast WebAssembly engine, so the whole live simulation runs in JavaScript. | Nothing is wrong. The results are the same, only slower. A diagnostic names the part. |
| A long run seems stuck | It's still running. Vendor models are slow: twenty of them can take 30 seconds. | Watch the progress bar. Cancel stops the run. |
| "A simulation is already running (N s, P %). Press Cancel to stop it, then Simulate again." | You pressed F5 during a run. | Wait, or press Cancel first. |
| "This run uses the built-in engine and cannot be cancelled; it stops by itself when it reaches the stop time." | Browser version: its engine runs to the end. | Wait, or shorten Simulate for next time. |
| "The circuit changed while the transient ran; its result was discarded." | You edited the circuit during a run. | Run it again after the edit. |
| The live simulation runs slower than the timebase | The computer can't keep up, so circuit time slows down rather than becoming inaccurate. | Use a slower timebase, or close pop-out windows. |
14.5Models and the library
First check. First look at the status dot of the model row: green runs as it is, amber after conversion, red has a stand-in.
| What you see | Why | What to do |
|---|---|---|
ngspice not found in the status bar, or E_NGSPICE_MISSING | ngspice.dll isn't where BetterSPICE looks. | Reinstall, or set BSPICE_NGSPICE to its folder (ngspice for vendor models). |
| A banner: "Simulation failed:" and a reason | The run failed: usually a missing model file, ngspice missing, or no convergence. For ngspice failures the banner gives a short summary ("ngspice stopped at 2.158 ms: timestep too small near Q1", "singular matrix at …", "no DC operating point", "could not find model …") with the likely cause and what to try. The part ngspice names is mapped back to your part. | Do what Try says. Show full log opens ngspice's own log, one line per line, with Copy log. The diagnostic code is in Diagnostics. |
| "timestep too small" with a TI op-amp model | The model's output clamps switch abruptly when the op-amp comes out of saturation (for example when a regulator leaves dropout). | Simulate already re-runs it once with convergence aids (warning W_CONVERGENCE_AIDS). If that fails too, lower the maximum step and set Gear in , and check that the op-amp's supply is within its rating. |
| An op-amp output is a solid band in Simulate, or a regulator loses regulation at a high input, while the live view is clean | The assigned model is a comparator, not an op-amp (TLV902x, TLV18xx, LMV393 …): in a linear loop it switches on and off. Some TI comparator models float their output to mid-supply above the supply rating. | Assign an op-amp model. Keep the supply of the part within its rating. |
| A run with an encrypted TI model stops | Another PSpice run is going. | Close your own PSpice and run again (Run a model that is encrypted). |
| A Needs PSpice badge on a model row (Needs PSpice · not found, dashed) | The model is encrypted by Cadence. Only PSpice can run it. not found: PSpice isn't on this computer, so the fitted behavioural model is used (approximate). | Hover the badge for the steps. Windows: PSpice for TI. Linux: Wine + PSpice for TI. macOS: not available. |
| The status bar says no PSpice after Accurate | PSpice wasn't found (on Linux: Wine, or PSpice in its prefix, is missing). Everything else works. | Hover it for the steps, install, and restart BetterSPICE. It says PSpice found once it's there. |
| A message that a model was replaced when you placed it | The model fails in every engine, and a working model of the same part stands in. | Nothing. The stand-in is the same part from another library. |
| A model you knew isn't in the library | It can't run in any engine and was retired. | Look in library/broken/index.csv for the reason, and choose another library's model of the part (Retired models). |
| "its N pins (…) do not match this op-amp: Simulate may wire it wrongly" | The model has another pin order from the symbol. | Place the model from the library instead, so it brings its own pins. |
| "No compatible model … Use the Quick model tab" | Nothing in the catalogue fits this kind of part. | Build one from the datasheet (Get a model from datasheet numbers). |
14.6Files, import, agents and install
First check. First look at the message at the bottom of the window. It names the file and the reason.
| What you see | Why | What to do |
|---|---|---|
| A circuit dropped on the window opens as … · not saved | A dropped file opens as an unsaved copy, without its path. | Use (Ctrl+O) or double-click the file in Explorer to keep working on the file itself. |
| Ctrl+S on an example or an import asks for a name | They have no file of their own yet. A tab marked example isn't your file. | Choose a folder and a name. Later saves go there without asking. In the browser the name is asked for in the window, and Esc keeps the circuit unsaved. |
| Help › User manual (PDF) is missing | BetterSPICE didn't find BetterSPICE-User-Manual.pdf next to the app or in the repository, or the browser's server doesn't serve it. The user guide (Help › User guide, F1) is part of the app and is always there. | Put the PDF in docs\manual next to betterspice.exe. |
| I can't find a tab | Many tabs are open and the strip scrolls. | Click the down-arrow button at the right end of the tab strip for the list, or use the ‹ › arrows. |
E_FILE: a file can't be opened or saved | Missing, read-only, a folder, over 64 MB, or not UTF-8 JSON. | The message names the file and the reason. |
| "Recovered N unsaved circuits from <date>. Save to keep it." | The app closed with unsaved work. Autosave kept a copy. | Save each recovered tab (Ctrl+S). |
| An imported board reads 0 V everywhere: "No supply in the imported circuit: add a DC source" | No source in the import, or ICs without models. | Add a DC source on the supply net, and assign models to the ICs that matter (Import a KiCad or EasyEDA Pro design). |
| A hierarchical KiCad design imports without its sub-sheets | A single .kicad_sch can't bring its sub-sheet files. | Zip the project folder and import the zip. |
| AI agents cannot connect | The control port could not open, usually because another program uses it. | Set BSPICE_PORT to a free port for both the app and the agent (Working with an AI agent). |
| An agent reports "this ran headless on files, NOT in the BetterSPICE window" | The agent didn't reach the running app, so it edited the file on disk. | Check the port and the token, then ask again (Hand a task to an AI agent and check what it did). |
| The window opens off screen or squeezed | Window and pane sizes from a larger monitor. | . Sizes saved on another monitor are fitted to this one. |
14.7Reporting a problem
- Save the circuit (Ctrl+S). The file is plain JSON and holds everything needed to reproduce a result.
- Write down what you pressed, what you expected and what you saw.
- Copy the text of any diagnostic, banner or message.
- Attach
%APPDATA%\BetterSPICE\betterspice.log. shows that folder.