Errors · Inkoxide

Mistakes fail loudly, with the component that caused them: a style key or value an element cannot use, and a prop it would ignore (<Page wrap={false}>, href on a Cell or a Header, className on an SVG shape, render on an Image). An error inside a render prop names the components around it too. A View inside a Text:

<Text>Total: <View /></Text>

stops the render with:

RenderError: <View> cannot be inside <Text>. A Text contains only strings, numbers,
<Text>, <Link>, <Image>, <Note>, <PageNumber> and <TotalPages>.
    in View
    in Text
    in Page
    in Document
    in Receipt

Every error of renderToBuffer, renderToStream, renderToFile and init is a RenderError with a code and an HTTP status, and with path, component and componentStack where they apply:

Code	What happened
`TEMPLATE_ERROR`	A component used in the wrong place, a prop with an invalid value (a bad `Page` `size`, a `Link` without `href`), an unknown style key, an unknown Tailwind class (outside production; there it is logged once and ignored), a component or `render` prop that throws, or an image `src` that cannot be used: a URL outside `remoteImages`, a path while `localImages` is off (from a function), or a function or promise that fails or does not settle in `imageTimeoutMs`
`INVALID_TREE`	The document tree does not match the engine's schema. Checked only with `validate`, which is on outside production
`INVALID_FONT`	A registered font could not be read, fetched or parsed
`ENGINE_REJECTED`	The engine refused the document, for example an unreadable image, or a render option is out of range (`path` is `options.threads`, `options.creationDate`, …)
`IMAGE_FETCH_FAILED`	An allowed remote image could not be fetched: an HTTP error, a redirect, a timeout, a dropped connection or over `maxBytes`
`IMAGE_READ_FAILED`	An image file could not be read: missing or outside the `localImages` folders, a network path, not a valid `file:` URL, not a regular file, over the size limit, permission denied, or a `localImages` folder that cannot be opened
`INTERNAL`	The engine could not start (no fonts in the assets folder, `inkoxide` and `@inkoxide/schema` versions that do not match), a bundled font or hyphenation file could not be read or, in a browser, fetched (`engineCode` `NOT_LOADED`), `renderToFile` could not write the file, or a bug

INTERNAL has status 500, IMAGE_FETCH_FAILED 502 and the others 400. Besides code, status, message, path, component and componentStack, a RenderError may have className (the Tailwind class that failed), engineCode (the engine's own code, for ENGINE_REJECTED and some INTERNAL errors) and issues (for INVALID_DATA). It turns into JSON with only its fields that are set (res.status(e.status).json(e)): code, message, path, component, componentStack, className, engineCode and issues, but not status or the stack. Two more codes come from templates: INVALID_DATA (400) and UNKNOWN_TEMPLATE (404).

Font.register and Font.registerHyphenationCallback check their arguments when you call them and throw a plain Error straight away: a missing family name or src, a src that is not a path, a URL or bytes, an unknown weight, a face already registered from another source, a face the bundled fonts have, or a family whose font id another family has.