// 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. |
| 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. |
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.