Diagnostic codes
Diagnostic codes
Every code keeps its level; renaming or removing one is a format change.
| Code | Level | Line | Meaning | Fix |
|---|---|---|---|---|
source. | error | The source exceeds the 16 MiB limit. | Split the report or shrink its inline data below 16 MiB. | |
frontmatter. | error | yes | The frontmatter is not YAML. | Rewrite the frontmatter between the — lines as valid YAML. |
block. | error | yes | A rich block’s YAML is not YAML. | Align sibling keys at the same indentation, indent nested fields consistently, and use key: value mappings. |
yaml. | error | yes | The YAML uses a feature outside the RichView profile, such as anchors, tags or several documents. | Remove anchors, aliases, tags and extra documents; write plain YAML. |
yaml. | error | yes | A mapping repeats a key. | Delete or rename the repeated key so each key appears once per mapping. |
frontmatter. | warning | yes | A frontmatter field has the wrong type and is dropped. | Give the field a value of the type the message names, or remove it. |
frontmatter. | error | yes | Closed frontmatter is not a mapping, so the title block cannot be read. | Write the frontmatter as a YAML mapping, such as title: A report, or remove its delimiters to render it as body text. |
frontmatter. | warning | yes | A frontmatter key the registry does not know; it stays in the metadata with no effect. | Remove the key, or rename it to the known key the message names. |
frontmatter. | warning | yes | The frontmatter has no closing line, so it is rendered as Markdown. | Close the frontmatter with a --- line after its last key. |
frontmatter. | warning | yes | The version is not semver-shaped and is dropped. | Use a quoted semantic version such as version: "1.0.0"; remove literal backslashes around the quotes. |
frontmatter. | error | yes | A frontmatter key the format retired; the fix names its replacement. | Replace the retired frontmatter key with the replacement the message names. |
frontmatter. | warning | yes | The date is not YYYY-MM-DD or RFC 3339; it renders as written. | Use an ISO date such as date: 2026-10-30, or an RFC 3339 date-time such as date: 2026-10-30T08:00:00Z. |
frontmatter. | warning | yes | The language is not a supported locale; the page language is set but formatting stays English. | Set lang to en, en-GB, cs, de or ja to print numbers in that language’s format; any other tag only names the page language. |
frontmatter. | error | yes | The format marker is not rmd/, or names a newer major version than this renderer reads. | Set format: rmd/<major> to a major version this renderer reads. |
frontmatter. | warning | yes | The tabs setting is malformed, so the body renders without tabs. | Write tabs as a mapping whose panels give each tab a unique id, a label and the heading anchor it starts from. |
frontmatter. | error | yes | Report header data is no longer supported; data belongs in each block. | Remove the header data and give each block its own data source. |
publish. | error | Publishing needs a title, a description and a version. | Add a title, a description and a version to the frontmatter. | |
block. | error | yes | A rich block is not a YAML mapping. | Make the block’s YAML a mapping of keys to values. |
block. | error | yes | A block field is missing or has the wrong type or value. | Give the field the value the message asks for; richview learn lists each block’s fields and their types. |
block. | error | yes | A field reference names a column the block’s data does not have. | Name a column that exists in the block’s data, or add that column. |
block. | error | yes | A block key, tag or value the format retired; the fix names its replacement. | Replace the retired key, tag or value with the replacement the message names. |
block. | warning | yes | A block key the registry does not know; it is dropped before rendering. | Remove the key, or rename it to the known key the message names. |
schema. | error | A value fails the public schema parse. | Fix the value so it matches the public schema for that field. | |
data. | error | yes | A block does not define exactly one local data source, or uses a header id or remote address. | Keep exactly one data source (inline, csv, json, url, sql, metricflow or cache) and remove the others. |
data. | error | yes | A block’s data file was not resolved before rendering. | Resolve the data file before rendering, or render through the CLI or host. |
data. | error | yes | A resolved dataset exceeds 16 MiB. | Reduce the dataset below 16 MiB by filtering rows or dropping columns. |
data. | error | yes | A CSV dataset cannot be read. | Repair the CSV so it parses: consistent columns, valid quoting, UTF-8. |
data. | error | yes | A CSV dataset’s headers are empty or repeat. | Give every CSV column a non-empty, unique header. |
data. | error | yes | Inline rows are not flat row mappings. | Write inline data as a list of flat row mappings, one value per key. |
frontmatter. | warning | yes | The slug is not valid, so publishing fails until it is fixed. | Write slug as 1 to 80 characters of a-z, 0-9 and single hyphens, with no hyphen at either end, such as q3-sales. |
publish. | error | The slug is not valid for publishing. | Use a slug of lowercase letters, digits and hyphens. | |
publish. | error | This version is already published with different content. | Bump the version, or publish content identical to the existing one. | |
publish. | error | This version was deleted and its number cannot be published again. | Publish under a new, higher version number. | |
publish. | error | The pinned version is not published for this report. | Pin a version that is published for this report, or drop the pin. | |
publish. | error | This report address is new and needs --new to be created. | Pass --new to create this report address, or correct the slug. | |
publish. | warning | The slug was derived from the title because the frontmatter has none. | Add a slug to the frontmatter so the report keeps its address when its title changes. | |
publish. | error | Publishing would exceed the storage quota. | Delete old versions or shrink the report to fit the storage quota. | |
data. | error | yes | A JSON dataset is not an array of row mappings. | Make the JSON file an array of flat row mappings. |
data. | info | yes | A connector query was run and its result stands in for the block’s data. | Nothing to change; this records which connector query supplied the block’s data. |
data. | warning | yes | A cached snapshot exceeded its freshness limit; the reader’s data-source note marks it stale. | Run the query again to refresh the snapshot, or keep it; the reader’s source note says it is stale. |
data. | error | yes | A data block names a connector that is not registered. | Use a registered connector name, or register the connector first. |
data. | error | yes | A connector refused the query. | Correct the query or its parameters to what the connector accepts. |
data. | error | yes | A connector failed while running the query. | Check the connector’s access and the query, then run it again. |
data. | error | yes | A connector hit a file error. | Check that the connector’s file exists and is readable. |
data. | error | yes | A data block references a cached result that does not exist. | Run the query again to fill the cache, or remove the cached reference. |
image. | error | yes | An Unsplash photo has no credit, so the block stays source. | Add the photographer’s credit to the Unsplash image. |
image. | error | yes | An Unsplash photo’s credit breaks the rules, so the block stays source. | Fix the Unsplash credit to follow the credit rules. |
image. | warning | yes | An optional image credit has no non-empty author, so no credit is shown. | Give credit. the creator’s name, or remove credit. |
image. | warning | yes | A credit link is not an http(s) address, so the name is not linked. | Make the credit’s author_ and source_ http or https addresses, or remove them. |
image. | warning | yes | An image color is not #rrggbb and is dropped. | Write color as a #rrggbb hex colour, such as #1f6feb, or remove it. |
security. | warning | yes | An audio or video source was blocked as unsafe. | Use an audio or video file in the report folder, or a data: URI of an audio or video type. |
security. | error | yes | An embed was blocked because its URL is not https, carries credentials or names a host that is not allowed. | Use an https embed URL on an allowed host. |
export. | warning | yes | A video has no poster, so the PDF prints a text card. | Add a poster image from the report folder so the PDF shows a frame of the video. |
assets. | info | yes | The report needs an external file that is not embedded. | Generate the report with richview generate, which embeds the report folder’s files, so it needs nothing beside it. |
assets. | info | yes | The report needs network access to load an asset. | Nothing to change if readers are online; offline, the photo or embed does not load and its placeholder shows. |
markdown. | warning | Math could not be rendered. | Correct the TeX the message quotes, or write the formula as plain text. | |
security. | warning | Unsafe raw HTML was removed. | Write the content in Markdown or a rich block; raw HTML never renders. | |
security. | warning | A Markdown image protocol was blocked. | Use an image file in the report folder or a data: image URI. | |
security. | warning | A Markdown link protocol was blocked. | Link to an http(s), mailto or tel address, a # anchor or a file in the report folder. | |
asset. | error | A remote asset reference is not a mapping. | Write the remote asset as a mapping with url, bytes, sha256 and type. | |
asset. | warning | A remote asset reference has a key it does not take. | Remove the key; the message lists the keys a remote asset reference takes. | |
asset. | error | A remote asset reference has a missing or unusable url. | Set a valid https url on the remote asset. | |
asset. | error | A remote asset url carries a signing parameter. | Use a stable public URL without signing parameters. | |
asset. | error | A remote asset reference lacks a valid byte size. | Set bytes to the asset’s exact size as a positive integer. | |
asset. | error | A remote asset reference lacks a valid SHA-256. | Set sha256 to the asset’s 64-character hex digest. | |
asset. | error | A remote asset reference has a media type its use does not allow. | Set a media type that this use of the asset allows. | |
asset. | error | A remote asset reference is neither public nor private. | Set visibility to public or private. | |
asset. | error | A remote asset’s duration is invalid or does not apply. | Set a valid positive duration, or remove it where it does not apply. | |
asset. | error | A remote asset’s width or height is invalid or does not apply. | Set valid positive width and height, or remove them where they do not apply. | |
style. | error | A styles file is not in the report folder. | Put the styles file inside the report folder and name it correctly. | |
style. | error | A style names a builtin that was renamed. | Replace the style name with the one the message names. | |
style. | warning | The style is still dark after the print swap, so the page prints with Air’s surfaces and inks. | Give the style light surfaces and dark inks to print in its own colours; otherwise paper uses Air’s. | |
style. | error | A styles entry names no built-in style. | Use a built-in style name, or a styles file in the report folder. | |
style. | warning | A style file is not a YAML mapping. | Write the style file as a YAML mapping of style keys to values. | |
style. | warning | A style leaf is retired and ignored. | Remove the retired leaf; the message says why it no longer applies. | |
style. | warning | A style leaf is invalid. | Give the leaf a value of the type the message names, or remove it. | |
style. | info | The brand colour was adjusted to meet the contrast floor. | Keep the adjusted colour for legibility or choose a brand colour with enough contrast. | |
style. | info | The secondary brand colour was too similar for the chart palette. | Choose a second colour that is distinguishable from the first, or keep the derived palette. | |
style. | warning | A distinct brand palette could not be derived. | Choose another brand colour or supply a checked explicit palette. | |
style. | warning | A company colour is translucent or unresolved. | Use an opaque concrete colour such as #0B6E69. | |
style. | error | Custom style properties are invalid. | Fix the custom style properties to the documented names and values. | |
style. | warning | The host has no bundled fonts, so text falls back to system fonts. | Generate the report with the CLI, which embeds the bundled fonts. | |
style. | warning | A style leaf is not in the style vocabulary and is skipped. | Remove the leaf, or rename it to the style key the message names. | |
style. | warning | A style leaf is experimental: it can break the layout in ways nobody expects. | Remove the leaf, or keep it only after checking the report at phone and desktop widths. | |
style. | warning | A style leaf fixes the page’s mechanics and is ignored. | Remove the leaf; the page sets it itself. | |
style. | warning | A style colour is below its contrast floor on a surface. | Darken or lighten the colour until it reaches the floor the message names on that surface. | |
style. | warning | Two neighbouring type sizes are closer than the minimum ratio. | Move the two sizes apart until each step is at least the ratio the message names. | |
style. | warning | The style embeds more than three font weights. | Use at most three font weights across the style. | |
style. | warning | A declared font family has no bundled face and no file in the report folder. | Add the font’s files to the report folder, or choose a bundled family. | |
style. | warning | Characters of the report fall outside the faces the style embeds. | Choose a face that covers these characters, or add one to the report folder that does. | |
options. | error | The render options’ styles are not an ordered array of style references. | Pass the render options’ styles as an ordered array of style references. | |
options. | error | A chart width is non-finite or outside 240 to 4096. | Set every chart width to a finite number from 240 through 4096. | |
render. | error | The render output option is invalid. | Set the output option to a value the renderer accepts. | |
render. | error | The render page option is invalid. | Set the page option to a value the renderer accepts. | |
render. | error | The generated report exceeds the 64 MiB HTML limit. | Shrink the report’s data, images or charts below the 64 MiB HTML limit. | |
assets. | info | The preview loads the chart runtime from outside the report. | Nothing to change in a preview; richview generate embeds the runtime for offline readers. | |
security. | warning | yes | A heading id or footnote label reserved for the report runtime was dropped or renamed. | Choose an id or label that does not start with rv, richview, tab- or panel-. |
security. | warning | yes | Heading classes and attributes from source were dropped. | Remove the classes and attributes from the heading, keeping only {#id}. |
image. | warning | The header image has no alt text, so it is treated as decorative. | Describe the image in alt, or write alt: "" to mark it decorative. | |
editor. | error | The editor service could not answer a request. | Retry the request; restart the editor service if it keeps failing. | |
block. | error | yes | A rich block sits inside a list, quote or note. | Move the rich block out of the list, quote or note to the top level. |
block. | warning | yes | A fence names no rich tag; a close match is suggested. | Change the fence tag to the rich tag the message suggests, or keep the fence as code. |
callout. | warning | yes | A callout has no title, so colour alone carries the finding. | Add a title that names the finding. |
block. | warning | A chart or table has no source note directly after it. | Add a source note directly after the block, such as Source: data/sales.csv., and name synthetic data as such. | |
table. | info | A table has no title or accessible name. | Add a title that names the table’s subject. | |
image. | info | The header image has neither a caption nor a credit. | Add a caption or a credit to the header image. | |
markdown. | warning | yes | An explicit heading id is not named by a tab panel and is ignored. | Name the anchor in a tab panel’s from, or remove the {#id}. |
markdown. | warning | yes | A Markdown table repeats a column header, making its columns ambiguous. | Give each table column a distinct header. |
table. | info | An inline table cell contains Markdown syntax and is shown as written. | Write the cell as plain text, or use a Markdown table in the prose when cells need emphasis or links. | |
media. | info | A video has no captions file. | Add captions with a WebVTT file from the report folder. | |
media. | info | An audio or video block has no transcript file. | Add transcript with a text or Markdown file from the report folder. | |
markdown. | warning | yes | A footnote reference has no definition and shows as text. | Add the footnote’s definition, [^label]: text, or remove the reference. |
markdown. | warning | yes | A sixth-level heading cannot move below the page title and stays at level 6. | Use at most five heading levels, with # for the top level. |
markdown. | warning | yes | The pull-quote marker is not supported and shows as text. | Write the quotation as a block quote and end it with — Name. |
markdown. | warning | yes | A wikilink is not supported and its label shows as text. | Write a Markdown link, text, in place of the wikilink. |
render. | error | The report could not be rendered. | Fix the errors reported with this one and render again. | |
style. | error | A style value holds characters the CSS output refuses. | Remove quotes, braces, semicolons and other CSS-breaking characters from the style value. | |
table. | warning | yes | A table total skips columns it cannot sum. | List the columns to sum, such as total: [accounts, revenue]. |
security. | warning | The chart runtime address is not allowed. | Use the embedded runtime, or a root-relative path or an https base without credentials, query or fragment. | |
tabs. | warning | A tab panel’s anchor is not in the body, so the body renders without tabs. | Give the body a heading with the panel’s anchor, such as ## Costs {#costs}, or correct the panel’s from. | |
tabs. | warning | Tab anchors are not distinct and in document order, so the body renders without tabs. | List the panels in the order their headings appear, each starting from a different anchor. | |
chart. | error | yes | A chart block could not be read. | Fix the chart block’s fields to match the chart schema. |
chart. | error | yes | A chart failed to draw. | Check the chart’s data and encodings, then fix the errors reported with it. |
chart. | warning | yes | Only the first reader states of a chart were checked. | Nothing to change if the checked states are typical; fewer control values let every state be checked. |
chart. | info | yes | The chart aggregates rows before drawing. | Nothing to change if means and ranges are intended; choose style. to draw every observation, accepting its rendering cost. |
chart. | info | yes | The chart draws representative positions for several observations and reports the kept and total counts. | Nothing to change if reduction is intended; choose style. to draw every observation, accepting its rendering cost. |
chart. | error | yes | Several numeric rows share a bar category and series. | Aggregate the data so each category and series has one row. |
chart. | error | yes | Missing heatmap observations repeat an existing coordinate. | Remove the duplicate missing-value rows so each x and y appears once. |
chart. | error | yes | Several numeric rows share a heatmap coordinate. | Aggregate the data so each x and y coordinate has one row. |
chart. | info | yes | The histogram’s bins and measure, with the observations they hold. | Nothing to change; set binning. or binning. to choose other bins. |
chart. | info | yes | How the box plot was summarised: quartiles, whiskers and outliers. | Nothing to change; this records how the boxes and whiskers summarise the data. |
chart. | warning | yes | Axis bounds clip supplied intervals or estimates. | Widen axes. and axes. to cover every interval, or remove them. |
chart. | warning | yes | A label exceeds the chart’s viewport. | Shorten the text or give the chart more room. |
chart. | warning | yes | An interval has equal bounds and collapses to a point. | Check the row’s bounds; an interval narrower than the chart can show is drawn as a point. |
chart. | warning | yes | Chart text falls below 4.5:1 contrast on the chart surface. | Darken or lighten the ink token the message names. |
chart. | error | yes | The chart has no rows to draw. | Give the chart at least one data row, or remove the chart. |
chart. | warning | yes | The plot draws nothing. | Check that the data has values in the encoded fields and that not every series is hidden. |
chart. | info | yes | Some rows have no value and are drawn as gaps. | Nothing to change if the values are missing; fill them in the data to draw them. |
chart. | warning | yes | Some observations were left out of the chart. | Give every row the values the message names, or remove the rows. |
chart. | error | yes | The histogram options or data are invalid. | Use a numeric field with valid bin options and non-empty data. |
chart. | error | yes | Bubble sizes are negative or not numbers. | Make every bubble size a non-negative number. |
chart. | error | yes | Heatmap colour values are neither numbers nor recognised missing values. | Make the colour field numeric, or leave missing values empty. |
chart. | warning | yes | Two labels overlap. | Shorten the labels or widen the chart. |
chart. | info | yes | A label was left out for lack of room. | Nothing to change; shorter labels or a wider chart show more of them. |
chart. | info | yes | Only some category names are shown. | Nothing to change; shorter category names or a wider chart show more of them. |
chart. | warning | yes | A label does not fit at this width. | Shorten the names, or give the chart more room. |
chart. | warning | yes | Some observations have no size, so their bubbles are omitted. | Give the row a size value, or remove the row. |
chart. | error | yes | The heatmap’s colour field has no numeric values. | Give the heatmap’s colour field at least one numeric value. |
chart. | error | yes | A pie slice has a negative value. | Make every pie value zero or positive. |
chart. | error | yes | A value that must be a number is not. | Make the field a number: remove units, text and thousands separators. |
chart. | error | yes | The chart has more of something than its type takes; nothing is dropped, so it is not drawn. | Filter or aggregate the rows to fit the limit named in the message, or choose a chart type that takes more. |
chart. | warning | yes | The palette fails its rule on this chart, so patterns tell series apart. | Pick a palette whose colours differ more, or keep the patterns. |
chart. | info | yes | Points overlap because their strips are too narrow to spread them. | Widen the chart, filter the data, or facet it. |
chart. | warning | yes | More than eight series reuse colour slots. | Show fewer series, or split the chart into facets with encoding.. |
chart. | error | yes | A source value cannot be represented. | Replace the unreadable source value with a plain number or text. |
chart. | warning | yes | A chart style setting has a value the type cannot use, so its default applies. | Give the style setting a value this chart type uses, or remove it. |
chart. | warning | yes | A group has too few distinct values for the chart to draw it. | Give the group at least two different values, or leave it out. |
chart. | error | yes | Heatmap colour values lack x or y coordinates. | Give every heatmap row both an x and a y value. |
chart. | warning | yes | An annotation’s coordinates do not resolve against the chart. | Place the annotation at values inside the chart’s data range. |
chart. | warning | yes | A highlighted value matches no row. | Match the highlighted value to one in the data, checking its spelling. |
chart. | error | yes | A total exceeds the finite numeric range. | Use smaller values or rescale the data so totals stay finite. |
report. | error | No dedicated report folder, or its source is missing. | Put the report in its own folder with a single .rmd source. | |
report. | error | The report root or source name is invalid. | Use a valid report folder and a valid .rmd source name. | |
report. | error | A report path escapes the report folder or is ambiguous. | Keep every report path inside the report folder, without .. or links. | |
report. | error | The report folder holds duplicate paths or several .rmd sources. | Remove duplicate paths and keep one .rmd source per report folder. | |
report. | error | The report folder cannot be inspected. | Check that the report folder exists and is readable. | |
scrolly. | warning | yes | A scrollytelling step sets a chart control or option the chart does not have. | Use a control id and option value from the chart’s controls. |
chart. | warning | yes | A chart is taller on paper than the share of the page it may take. | Show fewer rows or categories, or give the chart a wider style., such as 16:9, so it prints shorter. |
report. | error | yes | An image, audio, video, poster, header image or Markdown image names a remote address. | Download the file into the report folder and reference it by relative path. |
report. | error | yes | An asset path escapes the report folder. | Move the asset into the report folder and reference it by relative path. |
report. | error | An asset is missing from the report folder. | Add the missing asset to the report folder or correct its path. | |
report. | error | The output path escapes the Rendered folder. | Write output inside the Rendered folder, without .. in the path. | |
report. | error | The output file name is not allowed. | Use an allowed output file name with a plain relative path. | |
report. | error | An authored asset collides with a generated output. | Rename the authored asset so it does not match a generated output. | |
report. | error | The interactive chart runtime is missing, so the report cannot be exported. | Build the chart runtime first, or export without interactive charts. | |
export. | error | No Chromium-based browser was found for PDF export. | Install a Chromium-based browser or point the export at one. | |
export. | error | PDF export is not supported on this platform. | Export the PDF on a supported platform, or use the HTML report. | |
export. | error | The browser failed while printing. | Retry the export; check that the browser starts and can print. | |
export. | error | The report did not settle before the timeout. | Retry the export, or reduce the report’s charts and images. | |
export. | error | Images could not be decoded for printing. | Replace the undecodable images with valid PNG, JPEG or SVG files. | |
export. | warning | The browser is older than the supported Chrome version. | Use a current Chromium, Google Chrome or Microsoft Edge. | |
export. | warning | A photo could not be loaded while printing. | Check that the photo’s address loads, then export again. | |
export. | warning | Glyphs were drawn in a system font instead of the embedded ones. | Choose a style whose faces cover these characters, then export again. | |
export. | warning | The PDF has no tags or outline. | Export with a current Chromium, Google Chrome or Microsoft Edge, which writes PDF tags and an outline. | |
export. | warning | The report requested an address while printing that PDF output does not load. | Put the file in the report folder so the report embeds it, then export again. | |
export. | info | A link to a report file prints as text. | Nothing to change; link to a public address if PDF readers should open the file. | |
export. | info | The font check did not complete. | Export again; until the check completes, the PDF may depend on this machine’s fonts. | |
export. | info | Chrome printed with its sandbox off because RichView runs as root. | Run RichView as an ordinary user so Chrome prints inside its sandbox. | |
resource. | error | A report resource could not be resolved. | Check that the resource exists in the report folder and is readable. | |
authoring. | warning | A key is not used by the block. | Remove the key, or move it to where the block reads it. | |
authoring. | error | A key names a data field that does not exist. | Use a field name that exists in the data. |