// undine docs
Troubleshooting
Troubleshooting is the place for symptom-first support material.
The current panel exposes enough runtime and cache information to create a practical first-pass diagnosis flow.
Why simulations break down
Fluid simulation is sensitive to numerical instability. Small inconsistencies between solver stages can cascade into visible artifacts or solver behavior that feels unreliable.
In longer simulations, even small differences between execution paths can accumulate and become visually noticeable.
Common artifact categories
Motion problems
- Excessive kinetic energy
- Unstable particle motion
- Particle clustering
Surface problems
- Unrealistic surface behavior
Where to look next
In the current manual structure, Simulation and Debug are the best follow-up pages when the problem appears numerical, while Meshing is the right next stop when the issue appears on the renderable surface.
Symptom-first checks
Use this table as a starting point before diving into individual solver settings.
| Symptom | Likely area | First checks |
|---|---|---|
| Run is unavailable or produces no useful result | Scene tagging | Check Objects tab counts for Domain, Emitters, and Colliders. Confirm the active object is not Role: NONE when object parameters are expected. |
| No liquid appears | Emitter setup | Confirm at least one emitter is tagged, inside the domain, and producing a reasonable POINTS count. |
| Simulation is very slow | Resolution and numerics | Lower Grid Resolution, reduce pressure iterations, shorten the frame range, inspect Substeps and CFL, and watch SIM FPS / AVG. |
| Playback feels blocked or too slow | SNAP preset | Use a less aggressive viewport update preset or reduce the number of displayed particles with Viewport Limits. |
| Fluid explodes or gains energy | Pressure and time stepping | Lower CFL target, increase substep safety, inspect pressure backend/fallback, and reduce vorticity or surface tension if they were increased. |
| Pressure log shows code=4 max_iters | FP32 floor / multigrid | Residual is plateauing in FP32 noise. Confirm the FP32 tolerance floor safety factor, consider enabling multigrid preconditioning or symmetric RBGS smoother. |
| Sim falls back to CPU repeatedly | Pressure retry chain | Inspect the retry chain steps in the log. If CPU is the steady state, the GPU PCG path isn't holding for this geometry — try MG, lower CFL, or reduce density correction strength. |
| Thick material looks too diffusive or loses ridges | Viscosity quality / rheology | Raise the quality preset (PRO Lite or Thick Exact), add a positive base viscosity or a rheology model, and set yield_stress for hold-shape. Thick Exact needs a positive viscosity or active rheology to engage. |
| Viscosity spikes or NaNs in sheared zones | Rheology clamps | Raise rheology_gamma_dot_eps, review nu_min / nu_max clamps and density_ref, and check imported values for non-finite coefficients. |
| Viscoelastic memory does nothing | VISC-PRO gating | Confirm memory is enabled with model = maxwell_oldroyd_b and yield > 0 for hold-shape. Under FULL Resident strict it blocks unless Allow CPU Bridge under Strict is on. Upper-convected is not wired yet. |
| Fluid sticks, bounces, or jitters near colliders | Collider SDF | Check collider tags, bake animated colliders, then tune boundary band, contact radius, normal damping, and tangent friction. |
| Animated collider only collides on the rest pose | Bake colliders (animated) | Confirm Bake colliders (animated) ran. Armature / shape-key deformation must propagate before each frame's trisbin export — fixed in 0.0.314, but check the bake log if older. |
| Particle clumps or holes appear | Particle distribution | Review separation, density strength, reseeding thresholds, Min/Max PPC, and adaptive PPV settings. |
| Mesh looks like marbles instead of fluid | Meshify scalar route / anisotropy | Use a final preset (final_hero / final_ultra) — they force DENSITY_MC scalar route and enable anisotropy. The VDB scalar route does not invoke the anisotropic kernel. |
| Mesh has surface holes after raising influence | Meshify iso threshold | Influence radius up + iso value too high → surface punctures in sparser regions. Lower iso_value gradually. |
| Mesh is too noisy | Meshify quality | Increase smoothing carefully, use density filtering, check influence radius, and verify the simulation particle cache is complete. |
| Mesh is too heavy | Meshify resolution | Increase voxel size, lower quality preset, adjust decimation, and watch triangle count during meshify. |
| Meshify reports missing frames or fallback | Mesh cache and backend | Check Meshify cache frames/missing, backend policy, and whether the simulation playback cache covers the intended frame range. |
| Streamflow preset seems ignored | Runtime contract / preset routing | Confirm the Meshify-tab unified preset is the one expected; the runtime contract takes precedence over global preferences. Inspect 'Meshify Preset:' label in Actions. |
| Render shows wrong / missing motion blur | Alembic .velocities | Confirm Meshify exported Alembic and the renderer reads the per-vertex .velocities attribute. No additional vector pass is needed. |
Viscosity route reasons
When an advanced viscosity route can't run as requested, Undine emits a parseable reason string instead of degrading silently. These are the common ones and what to do about them.
PRO Exact (pro_strain_rate) is host CPU only and has no real multigrid; the messages below reflect that. Use block_jacobi as the preconditioner in final presets.
| Reason | Meaning | Action |
|---|---|---|
| pro_strain_rate_multigrid_pending_using_block_jacobi3 | mg + warn was requested; there is no real MG, so block_jacobi was used. | Request block_jacobi directly in final presets. |
| pro_strain_rate_multigrid_unsupported_strict | mg + strict — fails before mutating state. | Switch the preconditioner to block_jacobi, or the policy to warn. |
| resident_pro_strain_rate_not_supported_release | GPU/resident PRO Exact was requested. | Use host presets. Warn → host fallback; strict → resident_blocked. |
| pro_strain_rate_memory_budget_exceeded | The host operator estimated more memory than the budget. | Lower resolution / active cells, or raise the budget intentionally. |
| pcg_max_iter_no_commit | The iterative solve hit max_iter without committing. | Raise max_iter, relax tolerance with QA evidence, or simplify the scene. |
| non_finite_coefficient | A non-finite viscosity coefficient appeared. | Review rheology clamps, density, gamma_dot_eps, and imported values. |
When a preset no longer behaves like itself
The Sim Params panel can show overrides against the selected preset. When a Water or other material preset behaves unexpectedly, inspect the override list before changing more controls.
Overrides such as PIC Blend, Pressure Iters, Pressure Fallback, CFL Target, Density Strength, and Surface Tension can substantially change the feel of the material.