Diagnostics and repair

Keep the .rmd and its local resources as the working state. Rendered can be regenerated. After an interrupted session, read the source, validate it and continue from the first hard failure:

Shell

richview validate first-report/report.rmd --format json
richview check first-report/report.rmd --format json
richview generate first-report/report.rmd --format json

Fix a missing data file

In the visits starter created by richview init first-report, change csv: data/visits.csv to csv: data/missing.csv. Run richview validate first-report/report.rmd. It exits with status 1 and reports:

Configuration

report.rmd:21 error report.asset.missing: Asset 'data/missing.csv' is absent from the report folder. Add the file there or correct its report-relative path.
Invalid, 3 rich blocks

With --format json, the diagnostic is carried unchanged in the result:

JSON

{
  "blocks": 3,
  "diagnostics": [
    {
      "code": "report.asset.missing",
      "column": 9,
      "fix": "Add the missing asset to the report folder or correct its path.",
      "level": "error",
      "line": 21,
      "message": "Asset 'data/missing.csv' is absent from the report folder. Add the file there or correct its report-relative path.",
      "path": "chart.data.csv",
      "tag": "chart"
    }
  ],
  "ok": false,
  "output": null,
  "status": "issues"
}

Restore csv: data/visits.csv, then validate again. The result has ok: true, status: clean and an empty diagnostics array. Keep the data inside its report folder; moving it into frontmatter or pointing at a remote URL does not repair the missing file.

Diagnose by symptom

Symptom	Next action
Multiple `.rmd` sources or an escaping path	Put each report in its own folder; move source backups outside it; fix paths to bounded local files.
YAML/schema failure	Read the diagnostic line/path, compare the block with the copyable example, repair indentation and required fields.
Chart renders as code	Inspect the rich-fence diagnostics; it needs a supported type, data mapping, encoding and a title.
Missing styling file	Restore the referenced YAML, or remove that reference to use builtin/default styling.
No change after a theme edit	Save the local YAML; check the ordered styles and explicit chart palette; regenerate or refresh the preview.
Export says runtime missing	Install the complete native release again; its report runtime is embedded. For a source build, run the documented build command before exporting.
A linked download fails after sharing	Include the copied files in the entire `Rendered` folder, not only its HTML.
A check succeeds but a label is hard to read	Inspect warnings and actual browser glyphs; shorten/reposition labels without changing values.
Publish returns unauthorized	Confirm the selected server and its token; the public static website is not a native publishing server.
Republish shows old content	Same slug/version is immutable; use a new version for the revised source.
VS Code preview or diagnostics are stale	Save referenced files, check workspace trust and the packaged native service, then reopen Live Preview.

--format json exposes machine-readable diagnostics and nonzero exits for hard failures. Geometry diagnostics include clipping, collisions and dropped-label provenance. Native checks estimate font bounds; desktop and mobile browser inspection adds actual font geometry. A clean check is evidence about the tested output, not a universal readability guarantee.

Keep the agent’s next step small

Give the agent the report path, the failed command and the diagnostic. Ask it to preserve observations, units, source references and caveats while fixing the source, then render again. A useful handoff contains the saved source/resources, output path, remaining warnings and the next edit; it does not need a system architecture dump.

For exact grammar, run richview learn grammar or read the full source contract. For a known good baseline, return to your first report.

Read a diagnostic

Each record carries a level, code, message and path, with a fix, expected value, retry guidance, file, line, column, tag or details where applicable. Locations start at 1 and include frontmatter. A named file makes the line relative to that data or style file; otherwise it refers to the .rmd. The same records travel through CLI, MCP, HTTP and editor surfaces.

status: clean means no errors or warnings. ok: true means no errors and can still carry warnings. An info record may explain a deliberate choice, such as missing observations or experimental styling. The output path can identify a repairable draft even when a block failed; inspect diagnostics and the command’s exit status together.

Find a code

Search documentation for an exact code, or open the diagnostic code reference. Its table comes from the schema registry.