---
title: "pyrofx bake report: errors, warnings, artifacts, exit codes"
description: "Read the bake_report.json every command writes: ok, errors, warnings that name the key to change, the files written, clip metrics, exit codes and error codes."
canonical: https://appliedmanifold.com/docs/pyrofx/report/
site: "Applied Manifold: The spatial compute cloud for 3D reality"
---

[Home](https://appliedmanifold.com/) / [Docs](https://appliedmanifold.com/docs/) / [pyrofx](https://appliedmanifold.com/docs/pyrofx/) / Report

DOCS // pyrofx

# Report

Every command prints the same JSON report to stdout and writes it to `bake_report.json`: `ok`, `errors`, `warnings` with a fix key and hint, `artifacts` and `metrics`. A failed run still returns a report with `ok` set to `false`. Exit codes and error codes are listed under Errors.

## Fields

| Field | Meaning |
| --- | --- |
| `ok` | `true` when the run succeeded. A failed run still returns a report, with `ok` set to `false`. |
| `errors` | Each error has a `code`, the `key` at fault and a message. |
| `warnings` | `code`, often `where` and `first_frame`, and the `fix.key` to change with a `fix.hint`. |
| `artifacts` | Every file: kind, width, height, size. |
| `metrics` | Clip metrics: `life_s`, `rise_speed_mps`, `aspect_at_peak`, `mean_coverage` and `loop_seam`, plus per-frame lists. |
| `metrics.leftover_divergence` | Worst pressure error of any step, as the solve counts it. |
| `metrics.stored_divergence` | Worst pressure error at the exported frames: `leftover_divergence` plus rounding from `solver.precision`. |
| `metrics.render_redos` | Number of frames rendered again. The renderer computes each frame's light volume twice and renders the frame again when the two disagree. After 4 failed tries the bake (the compile) fails (see [Errors](https://appliedmanifold.com/docs/pyrofx/report/#errors)). |

## Errors

A failed run still returns a report, with `ok` set to `false` and `errors` filled.

| Exit code | Meaning |
| --- | --- |
| `0` | Baked. The report may still carry warnings. |
| `1` | Invalid spec or arguments. The report lists every error. |
| `2` | Internal failure, reported as `GPU_ERROR`. This includes a frame whose lighting still disagrees after 4 tries (`metrics.render_redos`); that bake writes nothing. |
| `3` | A file could not be read or written. |
| `4` | This host cannot run bakes. |

| Code | Meaning | Fix |
| --- | --- | --- |
| `SPEC_SYNTAX` | The spec is not valid TOML | Correct the syntax; the message has the line and the parse error |
| `UNKNOWN_SECTION` | The spec has a section the module does not know | Use the nearest valid section named in the message |
| `UNKNOWN_KEY` | The spec has a key the module does not know | Use the nearest valid key named in the message |
| `BAD_TYPE` | A value has the wrong type | Give the type the message asks for |
| `BAD_VALUE` | A value is not in the allowed set, or is otherwise invalid | Follow the message; it lists the allowed values or the rule |
| `OUT_OF_RANGE` | A number is outside its allowed range | Set it inside the range the message states |
| `BAD_SET` | A field override is malformed or points at a missing list entry | Use `section.key` or `section.index.key`, and make sure the entry exists |
| `BAD_SPEC_NAME` | The spec file name does not end in the module's extension | Rename it, for example to `.pyro.toml` for pyrofx |
| `GRID_TOO_LARGE` | The domain needs more cells than the largest grid allows | Raise `domain.voxel_m`; the message states the minimum |
| `GPU_ERROR` | A compute job failed, or a frame's lighting disagreed on 4 tries (exit code 2) | Read the message and retry |
| `FILE_READ` | A file could not be read, usually the spec | Check the path and that the file is readable |
| `FILE_WRITE` | A file or directory could not be written | Check the output path and that it is writable |
| `UNKNOWN_TOOL` | No module by that name is registered | Use a name listed in the message |
| `BAD_ARGS` | Arguments are missing or invalid | Follow the message |
| `BAD_REQUEST` | The request body is not a JSON object | Send a JSON object |

## Warnings

| Code | Means | First key to change |
| --- | --- | --- |
| `DOMAIN_CLIPPING` | Visible gas reached a side or the top of the box | `domain.size_m` |
| `EMPTY_SIM` | Nothing visible in any frame | `emitters` |
| `TILE_CLIPPING` | Content touches the tile edge | `views.margin` |
| `NOT_RISING` | Hot gas that does not climb | `solver.buoyancy` |
| `FLAT_SHAPE` | Wider than tall, seen side-on | `solver.buoyancy` |
| `PALE_CORE` | No flame pixel nears white | `look.exposure` |
| `FLAME_CLIPPED` | Over a tenth of flame pixels at the encoding limit | `look.exposure` (lower) |
| `FLAME_NOT_EXPORTED` | There is flame but no sheet carries it | `export.channels` (add `"emissive"`) |
| `ENDS_VISIBLE` | A one-shot is still visible on its last frame | `domain.duration_s` |
| `STARTS_FULL` | A one-shot's first frame is already large | `export.start_s` |
| `LOOP_SEAM` | The loop's wrap shows | `export.loop_blend_frames`, `export.warmup_s` |
| `PRESSURE_LOOSE` | The solver missed its accuracy, or 16 bit precision could not hold a tighter one | `domain.substeps`, or `solver.precision = "full"` |
| `SEALED_SPACE` | Gas grows in a space it cannot leave (no open side, or a room sealed by obstacles). The growth is removed evenly, like pressure in a closed room | `domain.open_faces`, or `carve` a vent |
| `STEP_TOO_LARGE` | Gas crosses more than about two cells a step | `domain.substeps` |
| `COVERAGE_HIGH` | Mean coverage over a half; expensive to draw | `solver.smoke_fade` |
| `GRID_REDUCED` | Draft quality; expected | none |

Warnings are advice. Flat or cold elements avoid some through their settings; the examples show how. Ship when `warnings` is empty.

## Questions

### What does bake\_report.json contain when a pyrofx run fails?

Even on failure, bake\_report.json sets ok to false and lists each error code, key at fault and message.

### What causes a pyrofx bake to exit with code 2 and GPU\_ERROR?

It happens on a compute failure or when a frame's lighting disagrees four times in render\_redos.

### How do pyrofx warnings help fix issues like DOMAIN\_CLIPPING?

Each warning includes a fix.key and fix.hint, such as adjusting domain.size\_m when visible gas reaches a box edge.
