Error Messages & Diagnostics — Triage by Symptom

25.1 The Triage Workflow

When something goes wrong, this sequence finds the cause quickly.

25.1.1 Step 1 — Verify the defaults work

Before investigating a specific problem, verify the baseline. In the Default Model Parameters dialog, revert the aquifer attributes to Data Center defaults — constant values off, Data Center rasters on. Press SIMULATE. If this works, your customization was the problem; re-apply customizations one at a time until the issue reappears. If this fails, there's a platform or project-specific issue — save the model file and seek help.

25.1.2 Step 2 — Identify the symptom class

Which of these best describes what you're seeing?

25.1.3 Step 3 — Check specific diagnostic

Within each symptom section below, causes are listed in approximate order of frequency. Check the most likely cause first; move down the list only if it doesn't fit.

25.2 Convergence Failures

The solver finishes without converging to tolerance, hits max iterations, oscillates, or crashes with NaN. This section focuses on the numerical side; structural causes are in §25.5 and throughout.

25.2.1 Symptom — "Max iterations reached"

Solver finishes but reports max iterations reached without satisfying tolerance.

• Most likely: slow convergence on a large or nonlinear model. Fix: Increase max iterations (gmSolverID position 1) from 4000 to 8000 or 16000. See Ch. 24 §24.3.1.
• Next likely: over-tight tolerance. Fix: Loosen tolerance from 0.0001 m to 0.001 m if your question doesn't need sub-mm precision. See Ch. 24 §24.3.2.
• Structural possibility: large K contrasts (high-K lens next to low-K barrier). Fix: Smooth the K field slightly or refine the grid near contrasts.

25.2.2 Symptom — Iterations oscillate

Max head change swings positive-negative between iterations without decreasing toward tolerance.

• Most likely: nonlinear feedback (unconfined aquifer with wetting/drying, or strong head-dependent boundaries). Fix: Reduce damping from 1.0 to 0.5 or 0.3. See Ch. 24 §24.3.3.
• Next likely: wrong solver for the problem. Fix: Switch from Hybrid SOR (ID 15) to PCG (ID 1), which handles some nonlinear feedbacks better.
• For strong unconfined problems: switch to MODFLOW-NWT (MFsolverStr at gmSolverID position 20). NWT's Newton-Raphson handles nonlinear unconfined flow more robustly. See Ch. 20 §20.3.3.

25.2.3 Symptom — NaN / infinity / crash

Simulation produces NaN (Not a Number) values or crashes mid-iteration.

• Most likely: cells drying out and the solver couldn't handle it. Unconfined cells where the head drops below the bottom of the aquifer produce zero saturated thickness → divide-by-zero → NaN. Fix: Switch to MODFLOW-NWT which handles wetting/drying robustly. See Ch. 20 §20.3.3.
• Alternative: unreasonable input values — K = 0 somewhere, recharge = infinity, bottom elevation above top elevation. Fix: Verify input ranges; the Data Explorer (Ch. 8) can help inspect raw input arrays.
• Unlikely but possible: extreme grid aspect ratio (very thin cells next to very thick ones) causing numerical problems. Fix: Smooth out grid transitions or add refinement to avoid abrupt cell-size changes.

25.3 Water Table Issues

The simulation converges but the simulated water table is physically unreasonable. These are the most common "wrong but not broken" results.

25.3.1 Symptom — Water table everywhere above ground (entire domain in seepage)

Simulated heads exceed DEM elevation across most or all of the domain. Sometimes described as "flooded domain" or "entire domain is a spring."

• Most likely: recharge too high — the 10×-rainfall pitfall. Fix: Check recharge units (m/yr vs m/day vs mm/day vs in/yr). Expected range for humid temperate climates: 100-300 mm/yr. Factor-of-365 errors (day-vs-year) and factor-of-10 errors (cm-vs-mm) are the usual culprits. See Ch. 14 §14.7 for the full pitfall description.
• Next likely: DEM-as-drain not active or leakance too small. Without adequate surface drainage, recharge can't exit; the domain fills up. Fix: Verify DEM-as-drain is enabled in the Surface Drainage dialog with reasonable leakance (typical DrnL values 1e-4 to 1e-2 per-time-unit). See Ch. 14 §14.2.
• Also possible: wrong boundary conditions. A prescribed-head BC set higher than nearby land surface drives unphysical flooding. Fix: Verify prescribed heads against land surface; BCs inside the domain (islands) are especially prone to this.

25.3.2 Symptom — Water table everywhere far below ground

Simulated heads are well below the land surface everywhere; no seepage or springs anywhere.

• Most likely: recharge too low (10×-rainfall pitfall in reverse — factor-of-365 applied the wrong way). Fix: Check recharge units again. For the Great Lakes or similar regions with ~300 mm/yr actual recharge, values around 1 mm/yr indicate a unit conversion error.
• Next likely: overactive surface drainage. If DrnL leakance is set very high (say 0.1 per-time-unit or greater), the DEM-as-drain aggressively pulls water out faster than recharge can replenish. Fix: Reduce DrnL to typical values (1e-4 to 1e-2).
• Also possible: K too high. Excessive K moves water through the domain quickly; with the same recharge, steady-state heads sit closer to the lowest boundary head. Fix: Verify K against regional expectations. Ch. 23 Data Center datasets give typical values for specific regions.
• For deep-water-table regions (arid West, desert): the simulation may be right. In regions with low recharge and high K, deep water tables are physically correct. Verify against known regional water levels before assuming error.

25.3.3 Symptom — Water table unreasonable at a specific location

Most of the domain looks right, but one zone or feature has clearly wrong heads.

• Most likely: local feature error — zone with wrong K, well with too-large pumping rate, stream with wrong stage. Fix: Inspect the feature's attributes; compare against expected regional values.
• For deep depressions near pumping wells: pumping rate may be too high or screen interval wrong. Verify both; consider whether the rate is sustainable given local K.
• For unrealistic mounding: injection well rate may be too high, or a zone recharge override is excessive.

25.4 Mass Balance Issues

The mass balance chart shows Ins ≠ Outs. Small discrepancies are normal; large persistent discrepancies indicate numerical or conceptual issues.

25.4.1 What size of error is a problem

• Steady-state: mass balance should close to very small tolerance (<1% discrepancy). Anything larger signals a real issue.
• Transient: small discrepancies during rapid-change periods are normal — storage terms are being updated. Discrepancies should settle to small values at long times.
• Large persistent errors (>5%): numerical or conceptual problem.

25.4.2 Symptom — Persistent large mass balance error

• Most likely: solver didn't converge despite reporting "complete." Fix: Tighten convergence tolerance and increase iterations (Ch. 24 §24.3). Verify that convergence criterion is actually met in the simulation log.
• Next likely: geometric or feature issue — overlapping zones, polylines extending outside the domain, features on cells below the aquifer bottom, wells with screen intervals outside the aquifer. Fix: Inspect geometry; the Data Explorer (Ch. 8) helps check feature placement.
• For transient runs: time step too large for the physics. Fix: Reduce time step; verify that transient storage changes are being captured.

25.5 Wrong Flow Direction

Flow vectors or particle tracks point in directions that look physically unreasonable. This is often a structural issue rather than a bug.

25.5.1 Symptom — Flow pattern inconsistent with topography

Regional flow appears to go uphill, or across topographic divides, or in directions unrelated to known surface drainage.

• Most likely: prescribed-head BCs dominate. A boundary head set lower than local topography can pull water against topography. Fix: Check boundary specifications; verify prescribed heads are reasonable relative to land surface.
• Next likely: the model is right and your mental model is wrong. Regional groundwater flow doesn't always match topography — flow-through lakes, underflow beneath surface drainage divides, and regional confined-aquifer flow often don't follow surface topography. If the model is confident and you've checked inputs, it may be teaching you something about your site.
• Diagnostic: compare simulated flow pattern against independent information (baseflow measurements, flow-path tracer tests, isotope data) before assuming the model is wrong.

25.5.2 Symptom — Heads match observations but flow pattern is wrong

Calibration fit looks good (RMSE small) but the overall flow pattern is unrealistic.

25.6 No Solution / Empty Output

SIMULATE completes without obvious errors but the display shows no heads or other results.

25.6.1 Symptom — Display shows nothing after SIMULATE

• Most likely: display settings — heads are calculated but not rendered. Fix: In Analysis → Display Charts, verify that Water Table visualization is enabled. Check HideOverlay state in Tier 4 tools.
• Next likely: solver hit max iterations with no usable solution; result was effectively discarded. Check the simulation log for convergence status. Fix: Address convergence per §25.2.
• Alternative: all cells inactive — every cell is a BC or dried out. Fix: Reduce BC coverage; if dried-out cells are the issue, switch to NWT (Ch. 20 §20.3.3).
• Platform-level: a configuration issue suppressed output. Fix: Reload the model, press SIMULATE with defaults, verify default behavior. If defaults fail, save the model file and seek support.

25.6.2 Symptom — Simulation crashes during startup

Simulation fails before any iterations run.

• Most likely: invalid input — NaN in an input array, missing required field, referenced dataset unavailable. Fix: Inspect input values with Data Explorer; verify all Data Center datasets resolve.
• Next likely: geometric incompatibility — zero-thickness cells, overlapping zones of incompatible types. Fix: Check geometry; adjust until cells have positive thickness everywhere.
• For MODFLOW-export users: package inconsistency in the exported file set. Fix: Re-export from IGW-NET rather than editing the exported files.

25.7 Transport and Particle-Tracking Issues

Transport (Ch. 12) and particle tracking (Ch. 11) have their own failure modes beyond the flow problems above.

25.7.1 Symptom — Concentrations going to NaN or unphysical values

• Most likely: excessive time step for the transport process. Advection can overshoot between cells if time steps exceed Courant limits. Fix: Reduce transport time step; for the Magnet native transport solver, this usually means reducing the overall simulation time step.
• Next likely: dispersivity too large or too small. Very large dispersivity can produce numerical oscillation; very small can produce numerical diffusion or instability. Fix: Use typical values (Ch. 12 §12.6).
• Also possible: flow solution unstable at the boundary where concentration source meets zero-concentration domain. Fix: Stabilize the flow field first, then transport.

25.7.2 Symptom — Particles stall or don't move

• Most likely: particles released in very low-K zones with negligible velocity. Fix: Check that release locations are in the expected flow path; consider the Darcy velocity magnitude at the release cell.
• For backward tracking: particles released at locations with no inflow (prescribed-head sinks, dry cells). Fix: Verify the release cell's flow direction; ensure backward tracking starts at a realistic terminal location.

25.7.3 Symptom — Breakthrough curves stay at zero or saturate immediately

• Staying at zero: no contamination reaches the monitoring well within the simulation time, or monitoring not active. Fix: Check simulation time (long enough?); verify monitoring well placement on a flow path; verify concentration sources are active.
• Saturating immediately: monitoring well is at or adjacent to the source. Fix: Usually not a bug — the well is measuring source concentration directly.