Troubleshooting

What to check when a mesh, a solve or a licence does not behave.

Where to look first

Nabla writes everything it does to the Log Bar at the bottom of the window (toggle it from Options → Show Log Bar if it is hidden), and error-shaped lines also appear as a toast in the corner. The solver's own console output is copied into the log bar verbatim, so the line that explains a failed run is almost always there before you need to go looking anywhere else.

The traffic light stays red

The three lights at the right of the menu bar are a summary, not a mystery: hover the light for a tooltip, and hover the green light specifically for the full checklist summary. Red means a rule that would make the solve fail outright has not been satisfied yet — most often:

• a shape has no boundary condition and no neighbouring region either (the model is not closed);
• a region has no material or property assigned;
• a transient or time-harmonic setting is inconsistent (a zero or negative time step, a zero frequency in time-harmonic mode);
• a motion-zone rule is violated — two zones overlap, a region belongs to none, or a band is missing an interface.

Yellow means every rule passes but the model has unsaved changes; solving from a yellow state still works, it is only a reminder to save. Green means both checks pass.

"Singular matrix" or a solve that fails immediately

The system matrix is singular (has no unique solution) almost always because two boundaries are supposed to be linked but are not, or because a region is left electromagnetically floating with nothing pinning it down. Check, in order:

• every periodic/anti-periodic pair actually has a matching pair on the other side — a cut with a BC on only one of its two edges leaves the system undetermined;
• a Dirichlet(0) boundary exists somewhere on the model — a fully Neumann/periodic model with no fixed reference for A has no unique solution;
• a sliding-band interface has both rings correctly marked moving/at rest for the situation (see Boundary conditions — the sliding band) — a mismatched pair produces a degenerate constraint;
• the mesh has a zero-area or degenerate element, most often from two vertices that ended up coincident after a transform or an imported DXF with duplicate points at a seam.

Non-convergence in a nonlinear solve

An iron region with a real B-H curve makes every step nonlinear; watch the log bar for the iteration count and residual it reports each step. A run that never converges usually means:

• the excitation is far outside anything physical (a coil current orders of magnitude too high), driving the iron deep past saturation where the B-H curve is nearly flat and the Newton step struggles to find a direction;
• a transient or time-harmonic run has not been given enough time to settle — a rotating machine's torque and currents can still be in their initial transient for the first fraction of a second of simulated time; if a result looks wrong (including an unexpectedly small or negative torque), run further before reading it rather than trusting step zero;
• the mesh is too coarse across a thin air gap or lamination, which can make the tangent stiffness ill-conditioned even though the physics is reasonable.

"Habs out of range" and other field-lookup errors

This means the solver tried to look up a material property (permeability, typically) at a field magnitude outside the range the material's B-H curve was defined over — almost always a degenerate or badly shaped mesh element handing the interpolation an unreasonable field value rather than the material curve itself being at fault. Refine the mesh in the region the error points at, and check for slivers left behind by a transform or a DXF import with near-duplicate vertices.

Mesh generation fails or looks wrong

• "Triangle (the mesh generator) was not found" — nothing meshes, and the message lists the locations that were searched. Triangle is not bundled with Nabla (see Getting started — Installing for why); either re-run the Nabla installer and use its Download Triangle step, or fetch triangle.exe yourself from the Releases page of github.com/Ar4ibald911/Triangle and put it next to Nabla.exe, on your PATH, or anywhere you like with the NABLA_TRIANGLE environment variable pointing at it. The listed locations are exactly the ones Nabla will look at again, so putting the file in any of them is enough — and it does not matter which folder you start Nabla from.
• A closed pocket with no triangles inside it usually means the boundary is not actually closed — a gap of a fraction of a millimetre between two shapes that look joined on screen is enough; snap to existing vertices (point snap) when you draw the closing edge.
• Triangles appearing where you expected a hole (or vice versa) means a hole marker landed on the wrong side of a boundary, or a shape with self-intersections was fed to the mesher; check the shape for crossings before meshing.
• An imported DXF that meshes very differently from how it looked in your CAD package is a sign an unsupported entity (spline, ellipse, block insert, text) was silently skipped on import — see Geometry — DXF import and export for which entities Nabla reads.

Zero or unexpectedly small torque/force

Before suspecting the physics, rule out the two most common causes: the result was read before the run had settled (see non-convergence above — give a transient run real time before reading torque), and, for a rotor result, the probe or region the number comes from is not where you think it is once the rotor has moved — a fixed-position probe reads whatever material is under it at that instant, not a label that follows the rotor around.

Licence errors

The solver checks your licence independently of the application and never fails closed — a missing, expired or unrecognised licence falls back to the free tier rather than crashing. A refusal prints a line beginning LICENSE_ERROR: naming the capability it will not run, and Nabla raises a dialog with the same text. Common causes:

• the model uses a module your tier does not include (the thermal module, second-order elements, time-harmonic, Crank-Nicolson, far-field, or more than one motion zone);
• the mesh is larger than your tier's node budget;
• the licence has expired, is only in its grace period, or was activated for a different machine.

Open Help → Licence... to see the state of this copy, and the About dialog's Copy fingerprint button for the machine identifier support will ask for. An expired or missing licence never prevents you from opening a model or reading results you already have — only starting a new solve is refused.

After a crash

The first crash in a session triggers a best-effort emergency save of the current model before anything else happens, so recent work is not simply lost. Details of the run are appended to a log file next to the application (session_log.txt in a release build, crash_report.txt in a debug build) — attach that file if you report the crash. Repeated, identical crashes within the same minute are logged once with a repeat count rather than flooding the log.

The manual will not open

If Help → User Manual reports that it could not hand the manual to a browser, the dialog shows the path it found. Copy that path with Copy path and open the file yourself — the manual is ordinary HTML and any browser will read it.

Search finds nothing

The search box reads a small index file that ships beside the pages. If searching returns nothing at all — not even for a word you can see on screen — the copy of the manual you are reading is incomplete: assets/search-index.js is missing or was not unpacked. The contents list in the sidebar still works, and reinstalling restores the index.

Next steps

• Getting started.
• Solving — problem types, time integration and nonlinear settings.
• Back to the contents.