12  Troubleshooting

Input validation, mesh connections, convergence, and divergence diagnosis

12.1 Input file rejected

  • Confirm that the input file uses JSONC format (.jsonc extension with valid syntax).
  • Remove trailing commas and unquoted keys (JSON5 syntax is not supported).
  • Write mesh, materials, and domains as arrays, not wrapper objects.
  • Write mesh_zones, mesh_markers, and fields as string arrays.
  • Set analysis.solver to dbns, pbns, or fr.
  • Do not mix numerical_method subblocks that do not apply to the selected solver.

12.2 Mesh names not found

Mesh zone and marker names in the configuration must match names in the mesh file:

  • domains[].mesh_zones — zone names
  • domains[].boundaries[].mesh_markers — boundary marker names
  • interfaces[].side1_mesh_markers, side2_mesh_markers — interface marker names

Mesh format naming:

  • CGNS: zone and BC names
  • SU2: zone and marker tags
  • Gmsh: physical-group names

For multiple meshes using mesh[].scope, verify the actual scoped names (e.g., scope/zone).

12.3 Convergence failure

  1. Start with a low CFL using run_control.cfl.type=constant.
  2. Reduce the convective spatial_order to 1 and simplify the limiter.
  3. Check mesh quality and the physical consistency of boundary conditions.
  4. Enable monitoring.solver_state and solver monitors to identify the equation that is stalling.
  5. Use adaptive CFL for steady calculations only when needed. Adaptive CFL is unavailable for STANDARD unsteady calculations.

12.4 Solution divergence

  • Lower the initial CFL, then increase it gradually with run_control.cfl.type=schedule.
  • Check for strong shocks or low-Mach behavior and select an appropriate convective scheme.
  • For NS/RANS cases, check viscous and turbulence preconditioners and wall thermal conditions.
  • Use outputs.diagnostics.on_diverge to save the final state on divergence.

12.5 FR case errors

  • analysis.solver=fr requires analysis.time=unsteady.
  • Use the FR-specific numerical_method.fr block rather than copying DBNS keys. FR accepts rk4, euler, tvd_rk3, rk34, or rk45 for time_integration; it does not accept runge_kutta_explicit.
  • There is no time_integration: "dual". Dual time is switched on by run_control.time_stepping — use bdf1, sdirk3, or sdirk4. FR does not implement bdf2.
  • FR step-size and inner-loop keys live in run_control, not numerical_method.fr: timestep_control (physical Δt), pseudo_time (Δτ, including pseudo_time.adaptive), and convergence.inner (inner-loop bounds and residual gate).
  • Entropy filtering cannot be combined with run_control.timestep_control.controller=pi or with dual time.
  • FR output uses standard outputs.volumes[], not a separate fr_dump.
  • For cross-validation dumps, use outputs.restart or fr_reference_compare.