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 warnings list for deprecated or ignored inputs
a runtime failure reports its terminal status and, when available, an error in 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.

Missing reference temperature

If the response says reference_temperature is required, add that top-level field in °C. You must supply it whenever any thermal region is isolated, even if another region has a fixed-temperature or inlet boundary. It sets the total thermal energy in each isolated region. Choose the uniform temperature that represents that energy.

If all regions have temperature-setting boundaries, Vanellus can use the mean of the fixed-temperature and inlet-outlet boundary temperatures. Radiative ambient temperatures do not contribute to this mean, so a radiation-only model also needs an explicit reference. See reference-temperature selection for the complete rules.

Unbalanced power in an isolated region

If the response reports a thermally isolated part of the simulation, read its heating and cooling totals and the named power contributions. Check the contributing components, CTMs, linked fans, and boundary paths. The boundary breakdown includes the prescribed flux and its meshed area in that region.

Correct unintended signs or units, restore missing thermal contacts, or provide the intended heat-removal path. If the region should remain isolated, its prescribed heating and cooling must balance. Cooling in another disconnected region cannot compensate. Isolated thermal regions and power balance explains the check and gives examples.

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.

Vanellus Guide