Diagnose a rejected or failed simulation
Separate request rejection, runtime failure, and an unconverged result before changing the model.
Read the API feedback
Start with the feedback returned by the API:
- an unsuccessful submission includes a response body describing the validation failure
- an accepted submission includes a
warningslist for deprecated or ignored inputs - a runtime failure reports its terminal
statusand, when available, anerrorin the status response.
The downloadable clients print submission errors and warnings. If using curl, include --fail-with-body so an unsuccessful HTTP response does not hide its body. Address this feedback before trying to infer the cause from solver output.
Preserve the submitted request
Save the exact JSON sent to the API, not only the Python inputs used to construct it. Also retain the HTTP response or final status document. These identify whether the failure occurred before or after the simulation received an ID.
The downloadable Python client writes submitted-request.json for successful runs. For a failing workflow, write the request before submission so it is retained even when no result bundle is produced.
Diagnose a rejected request
A rejected request has no running simulation to inspect. Read the response body returned with the unsuccessful submission; validation messages identify the field or indexed component that failed.
Correct the reported input first. Common checks include:
- duplicate component or monitor names
- cuboids outside the domain or overlapping another component
- boundary regions on an invalid face or overlapping another condition
- incompatible model options
- values with invalid units, signs, or ranges.
Use a dry run for accepted requests
Set dry_run to true and resubmit the same complete model. A successful dry run confirms that the API accepts the request and can generate its geometry and mesh. Inspect the returned mesh for lost components, closed passages, or unintended fusing and culling before starting another full solve.
Interpret the final status
Use status to identify why the run stopped and completed to determine whether a result bundle exists:
| Outcome | Next action |
|---|---|
error or killed | Retain the status error and request (there is no result bundle to inspect). |
diverged | Download the diagnostic result and follow Troubleshooting instabilities. |
max_iterations_reached | Inspect residual and monitor histories to decide whether the run was still changing. |
canceled | Treat the fields as a partial result from the final completed iteration. |
residual_converged or monitor_converged | Validate the result (the stopping status alone does not establish correctness). |
When an error remains reproducible after reducing the request to the smallest failing case, retain that request, its response or status document, the simulation ID if one exists, and the API target used when reporting it.
See also
- Simulation status and result files explains status and result availability.
- Troubleshooting instabilities covers failures during SIMPLE iteration.
- Check a simulation result covers downloadable but potentially unusable outcomes.