Why Your SPICE Simulation Fails: Floating Nodes and Ground
A SPICE error message is rarely about the thing it names. singular matrix is not a numerical problem you need to understand linear algebra to fix — it is almost always a wiring mistake with a short list of causes.
This guide covers the errors people actually hit, what each one means, and what to change.
Why SPICE needs a ground
Every voltage is a difference between two points. "Node 2 is at 3.3 V" is meaningless on its own; it means 3.3 V relative to somewhere. That somewhere is the ground node, and SPICE calls it node 0.
Internally, SPICE writes one equation per node and solves them together. Without a reference, the system has infinitely many solutions — add one volt to every node and it still balances. There is no unique answer, so the solver reports that the matrix is singular.
This is the root of most simulation failures. Almost every error below is a variation on "some part of this circuit has no path to the reference."
What `singular matrix` means, and how to fix it
What it means: the equations have no unique solution.
The usual causes, most common first:
No ground at all. Nothing in the circuit is connected to node 0. Add a ground symbol to the negative terminal of your source.
A section isolated from ground. The circuit has a ground, but part of it is separated from it — typically by a capacitor. A capacitor is an open circuit at DC, so a node sitting behind one has no DC path to the reference. Real circuits solve this with a bias resistor to ground; so does the simulator. A large one, say 1 MΩ, changes almost nothing about the behaviour and gives the solver its reference.
A voltage source loop. Two voltage sources in parallel with different values, or a source shorted by a wire. There is no consistent answer — the equations are contradictory rather than under-determined.
A dangling component. A resistor with one end connected to nothing. Whether this is an error or is silently ignored varies between simulators; either way it is not what you meant.
What to do about `no convergence` and `timestep too small`
What it means: the solver could not settle on a stable answer.
This one is genuinely numerical, but the causes are still usually structural:
- An ideal switch or a very fast edge. Give a step source a nonzero rise time, even a nanosecond.
- No resistance anywhere in a loop. An ideal voltage source driving an ideal inductor has an infinite current slope. Add the series resistance the real part has.
- A model at its limits. A diode driven hard past its rating, or an op-amp asked for more output than its supply allows.
If a transient run fails but the DC operating point solves fine, the problem is in the time-stepping, not the topology.
Why you get `unknown device model` or `undefined subcircuit`
What it means: the netlist refers to a part that was never defined.
Every non-trivial component — a diode, a transistor, an op-amp — needs a .model or .subckt definition, and a netlist that names one without providing it will not run. This is the most common failure when a netlist has been copied out of a datasheet or generated by a language model that produced plausible-looking text.
This is also why CircuPilot never asks a language model for SPICE directly. Generation returns a typed intermediate representation whose component types are a closed set, and the converter emits only models it defines — so a generated circuit cannot name a model that does not exist. Text that merely looks like a netlist is the failure mode this avoids.
What a `floating node` error is telling you
What it means: a node has only one connection, so no current can flow through it.
Usually a typo — Out in one place and out1 in another creates two nodes where you meant one, each connected to a single component. Check that node names match exactly, including case.
Unconnected input pins on logic gates and op-amps cause the same thing, and they are easy to miss on a schematic where the pin looks tidy.
A checklist that catches most simulation failures
Before assuming the simulator is wrong:
1. Is there a ground? Node 0 must appear somewhere.
2. Does every node have at least two connections? One connection means no current path.
3. Can every node reach ground through resistors? Follow the path. If it only gets there through a capacitor, that is a DC-isolated node.
4. Do the node names match? n1 and N1 may or may not be the same node depending on the tool.
5. Is every model defined? Every diode, transistor and op-amp needs a .model or .subckt.
6. Does the DC operating point solve? If not, do not bother debugging the transient run yet.
Making the common case not fail
Most of these errors come from one omission — a missing or unreachable reference node — and it is an omission a tool can reason about rather than report.
CircuPilot detects a reference node automatically when you have not placed a ground symbol, so a voltage divider you sketched in ten seconds simulates instead of returning singular matrix. Placing a ground explicitly still overrides it, which matters as soon as the circuit has more than one candidate.
That does not make the underlying rule less worth knowing. Every voltage is relative to something, and when a simulation refuses to solve, the first question is almost always "relative to what?"
Related
If you are simulating a microcontroller circuit rather than an analog one, the failure modes are different — see how to simulate an Arduino circuit online.