@alxia/react-router 0.10.0 → 0.12.0

package/docs/troubleshooting.md

@@ -26,6 +26,13 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: reactRouter(): client is …, which is not a directory. …`](#typeerror-reactrouter-client-is--which-is-not-a-directory-)
 - [`TypeError: reactRouter(): … cannot be served at a path of its own name; rename it. …`](#typeerror-reactrouter--cannot-be-served-at-a-path-of-its-own-name-rename-it-)
 - [`Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'none'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-default-src-none)
+- [`Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`](#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-script-src-self-nonce-)
+- [`A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`](#a-tree-hydrated-but-some-attributes-of-the-server-rendered-html-didnt-match-the-client-properties)
+- [`useNonce()` is undefined on the server](#usenonce-is-undefined-on-the-server)
+- [`TypeError: InlineScript(): the code contains "</script" or "<!--", which ends or confuses the script element; escape it, such as "<\/script" inside a string`](#typeerror-inlinescript-the-code-contains-script-or----which-ends-or-confuses-the-script-element-escape-it-such-as-script-inside-a-string)
+- [`TypeError: createPageLanguage(): the fallback … is not one of the languages; got ….`](#typeerror-createpagelanguage-the-fallback--is-not-one-of-the-languages-got-)
+- [The error page shows in the fallback language](#the-error-page-shows-in-the-fallback-language)
+- [`Error: You must render this element inside a <HydratedRouter> element`](#error-you-must-render-this-element-inside-a-hydratedrouter-element)
 - [`alxia-react-router: … already exists, and reveal leaves it as it is. Run alxia-react-router reveal --force to overwrite it.`](#alxia-react-router--already-exists-and-reveal-leaves-it-as-it-is-run-alxia-react-router-reveal---force-to-overwrite-it)
 - [`alxia-react-router: no vite.config.ts in …. Run reveal from the app's root, beside vite.config.ts.`](#alxia-react-router-no-viteconfigts-in--run-reveal-from-the-apps-root-beside-viteconfigts)
 - [`alxia-react-router: … gives alxia() an entry reveal cannot read. …`](#alxia-react-router--gives-alxia-an-entry-reveal-cannot-read-)
@@ -44,6 +51,7 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: defineWorkerContract(): cacheVersion must be a non-empty name without '-', …`](#typeerror-defineworkercontract-cacheversion-must-be-a-non-empty-name-without---)
 - [`parseBrowserManifest(): not React Router's browser manifest …`](#parsebrowsermanifest-not-react-routers-browser-manifest-)
 - [`error: Cannot find package 'react' from '…/@alxia/react-router/dist/pwa/react/index.js'`](#error-cannot-find-package-react-from-alxiareact-routerdistpwareactindexjs)
+- [`error: Cannot find package 'isbot' from '…/@alxia/react-router/dist/entry/index.js'`](#error-cannot-find-package-isbot-from-alxiareact-routerdistentryindexjs)
 - [`startWorker(): no precache list. …`](#startworker-no-precache-list-)
 - [`TypeError: startWorker(): contract is required: …`](#typeerror-startworker-contract-is-required-)
 - [`error: Could not resolve: "workbox-core". Maybe you need to "bun install"?`](#error-could-not-resolve-workbox-core-maybe-you-need-to-bun-install)
@@ -53,6 +61,20 @@ a loader, a message React Router or the browser prints, or an error from
 - [`buildWorker(): build/client/offline.html does not exist`](#buildworker-buildclientofflinehtml-does-not-exist)
 - [`buildWorker(): … is outside ….`](#buildworker--is-outside-)
 - [`buildWorker(): Bun.build failed:`](#buildworker-bunbuild-failed)
+- [`Cross-site request refused`](#cross-site-request-refused)
+- [`Expected a JSON body`](#expected-a-json-body)
+- [`Malformed JSON body`](#malformed-json-body)
+- [`The form sent an input the API would refuse`](#the-form-sent-an-input-the-api-would-refuse)
+- [`alxia-react-router: the error catalogue (…) was not read`](#alxia-react-router-the-error-catalogue--was-not-read)
+- [`alxia-react-router: the error catalogue was not checked, keeping what is held`](#alxia-react-router-the-error-catalogue-was-not-checked-keeping-what-is-held)
+- [`alxia-react-router: the error catalogue was not warmed`](#alxia-react-router-the-error-catalogue-was-not-warmed)
+- [`alxia-react-router: ttlMs threw, using retryMs`](#alxia-react-router-ttlms-threw-using-retryms)
+- [`alxia-react-router: ttlMs is not a duration, using retryMs`](#alxia-react-router-ttlms-is-not-a-duration-using-retryms)
+- [`TypeError: createErrorCatalogue(): needs at least one language.`](#typeerror-createerrorcatalogue-needs-at-least-one-language)
+- [`<api>: <operation> (request <id>) answered <status> <code>`](#api-operation-request-id-answered-status-code)
+- [`<api>: <operation> (request <id>) answered <status> without GraphQL`](#api-operation-request-id-answered-status-without-graphql)
+- [`<api>: <operation> (request <id>) unreachable`, `timeout` or `invalid-response`](#api-operation-request-id-unreachable-timeout-or-invalid-response)
+- [`<api>: <operation> (request <id>) aborted`](#api-operation-request-id-aborted)
 
 **Types**
 
@@ -87,6 +109,14 @@ a loader, a message React Router or the browser prints, or an error from
 - [An update waits an hour](#an-update-waits-an-hour)
 - [The worker cannot fetch another origin](#the-worker-cannot-fetch-another-origin)
 - [The manifest is in the wrong language](#the-manifest-is-in-the-wrong-language)
+- [A form's own check shows the code (`todos.errors.…`) instead of words](#a-forms-own-check-shows-the-code-todoserrors-instead-of-words)
+- [A message shows its `{braces}`](#a-message-shows-its-braces)
+- [A refusal shows the API's raw message](#a-refusal-shows-the-apis-raw-message)
+- [`apiRefusal` returns undefined](#apirefusal-returns-undefined)
+- [The error page shows no request id](#the-error-page-shows-no-request-id)
+- [An action shows the error page](#an-action-shows-the-error-page)
+- [Behind a TLS proxy every action answers 403](#behind-a-tls-proxy-every-action-answers-403)
+- [Right after start, refusals read in the API's words](#right-after-start-refusals-read-in-the-apis-words)
 
 ## Thrown or printed
 
@@ -516,6 +546,202 @@ or `contentSecurityPolicy: false`. Better than `'unsafe-inline'`: a nonce
 per request, with `nonce: true` and `nonceOf(loadContext)` in
 `entry.server.tsx` ([guide](guide/csp-nonce.md#a-csp-nonce)).
 
+### `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-…'"`
+
+**When:** the root renders an `<InlineScript>` (a theme's boot script, say)
+and the policy names a nonce.
+
+**Why:** the script rendered with no `nonce` attribute, because
+`useNonce()` found no nonce: the server render has no `<DocumentNonce>`
+around the router (an entry of your own that does not provide it), so
+`InlineScript` renders a bare `<script>`. The browser then refuses it, and
+the page flashes the wrong theme.
+
+**Fix:** wrap the router in the nonce `secureHeaders({ nonce: true })`
+made, in `entry.server.tsx`, or pass one to the script:
+
+```tsx
+// app/entry.server.tsx
+import { nonceOf } from '@alxia/react-router';
+import { DocumentNonce } from '@alxia/react-router/document';
+
+return (
+	<DocumentNonce nonce={nonceOf(loadContext)}>
+		<ServerRouter context={routerContext} url={request.url} />
+	</DocumentNonce>
+);
+```
+
+or, for one script, `<InlineScript code={THEME_BOOT} nonce={nonce} />`.
+
+Check the response: `curl -s -A 'Mozilla/5.0 Chrome/130' http://localhost:5173/ | grep -o '<script[^>]*>'`
+should show `nonce="…"` on the boot script too
+([guide](guide/document.md#the-nonce-on-the-server)).
+
+### `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties`
+
+**When:** the page hydrates, and the warning names `<html>` with a `class`
+or `style` the server did not render.
+
+**Why:** a boot script (a theme's) sets `class` and `style` on `<html>`
+before React hydrates, so the DOM no longer equals the server's HTML.
+
+**Fix:** keep `suppressHydrationWarning` on `<html>`. It silences that
+element's own attributes only, not its children:
+
+```tsx
+// app/root.tsx
+<html lang="en" suppressHydrationWarning>
+	<head>
+		<InlineScript code={THEME_BOOT} />
+	</head>
+	<body>{children}</body>
+</html>
+```
+
+A warning on another element is a real mismatch: a `nonce` the browser hid
+is read by `useNonce()` from the document, so never pass it from loader
+data ([guide](guide/document.md#the-theme-boot-script)).
+
+### `useNonce()` is undefined on the server
+
+**When:** the page's inline scripts or `<CspNonceMeta />` render with no
+`nonce` attribute although `secureHeaders({ nonce: true })` set one, and
+`useNonce()` returns `undefined` in the root.
+
+**Why:** the server render has no `<DocumentNonce>` around the router. The
+entry of `@alxia/react-router/entry` adds it; an entry of your own, such
+as React Router's revealed one, does not, and `ServerRouter`'s own `nonce`
+prop only reaches the scripts React Router writes.
+
+**Fix:** re-export the package's entry, or wrap the router in your own:
+
+```tsx
+// app/entry.server.tsx
+export {
+	handleRequest as default,
+	streamTimeout,
+} from '@alxia/react-router/entry';
+```
+
+```tsx
+// An entry of your own
+import { nonceOf } from '@alxia/react-router';
+import { DocumentNonce } from '@alxia/react-router/document';
+
+<DocumentNonce nonce={nonceOf(loadContext)}>
+	<ServerRouter context={routerContext} url={request.url} />
+</DocumentNonce>;
+```
+
+([guide](guide/document.md#the-entry))
+
+### `TypeError: InlineScript(): the code contains "</script" or "<!--", which ends or confuses the script element; escape it, such as "<\/script" inside a string`
+
+**When:** a page renders an `<InlineScript code={…} />` whose code holds
+`</script` (in any case) or `<!--`.
+
+**Why:** the code is written into the page unescaped. A `</script` ends the
+element early, so what follows is HTML, not script, and can be markup an
+attacker chose; a `<!--` makes the HTML parser treat the following
+`<script` as part of the script's text. A nonce does not help: it only says
+the script may run. The component refuses the code instead of rendering it.
+
+**Fix:** keep the code a constant of the app and escape the sequence inside
+a string. The code that reaches `InlineScript` must contain `<\/`, which the
+browser's script reads as `</`, and which is written `"<\\/script"` in a
+source string literal:
+
+```tsx
+<InlineScript code={'document.title = "<\\/script>"'} />
+```
+
+Never build the code from user input; pass such a value through a `data-`
+attribute and read it from the script.
+([guide](guide/document.md#the-theme-boot-script))
+
+### `TypeError: createPageLanguage(): the fallback … is not one of the languages; got ….`
+
+```text
+TypeError: createPageLanguage(): the fallback "de" is not one of the languages; got ["en","fr"].
+```
+
+**When:** the module that calls `createPageLanguage` loads.
+
+**Why:** `fallback` is the language of a page whose root data gives none, so
+it must be one of `languages`. The usual cause is a fallback in another
+spelling (`en-US` for `en`), or a `languages` list built from a different
+source than the fallback.
+
+**Fix:** name a language of the list:
+
+```ts
+createPageLanguage({ languages: ['en', 'fr'], fallback: 'en' });
+```
+
+### The error page shows in the fallback language
+
+**When:** on an error document, the root's `<html lang>` or text shows the
+fallback language although the visitor uses another.
+
+**Why:** a child route's error keeps the root's loader data. React Router
+keeps `loaderData` for every loader that succeeded, so
+`useRouteLoaderData('root')` still has it in `Layout` and `ErrorBoundary`.
+The data is missing in only two cases:
+
+- the URL matches no route, which is a 404 that runs no loader at all, the
+  root's included;
+- the root's own loader threw.
+
+With no data, `pageLanguage(undefined)` has no language to read. In the
+browser it keeps the last language it saw and the one picked with
+`chooseLanguage`; a document the server renders as an error has seen
+neither, so the fallback shows.
+
+**Fix, 404:** add a splat route whose loader throws a 404, so the URL
+matches and the root loader runs:
+
+```ts
+// app/routes.ts: add it last in your route config
+import { route } from '@react-router/dev/routes';
+
+route('*', 'routes/not-found.tsx');
+```
+
+```ts
+// app/routes/not-found.tsx
+import { data } from 'react-router';
+
+export const loader = () => {
+	throw data(null, { status: 404 });
+};
+```
+
+**Fix, root loader:** keep the root loader to `{ language: alxia.language }`,
+with nothing fallible in it. Load fallible data in child routes, or catch it
+and return it as a field.
+
+**Fix, client:** none is needed: a failed client navigation keeps the last
+language through `pageLanguage`.
+
+### `Error: You must render this element inside a <HydratedRouter> element`
+
+**When:** under `react-router dev` or after `react-router build`, every page
+answers "Unexpected Server Error" with this message, once
+`entry.server.tsx` re-exports `@alxia/react-router/entry`.
+
+**Why:** the server holds two copies of `react-router`: the one that
+renders `ServerRouter` in the entry, and the one `<Links>` and `<Scripts>`
+in the root read. They share no context. `alxia()` from
+`@alxia/react-router/vite` keeps them to one (it inlines `/entry` and
+`/document`, by an alias in dev and in the build, so they import the app's
+`react-router`). The message means `@alxia/react-router` is listed in
+`ssr.external` and `alxia()` is not in use.
+
+**Fix:** add `alxia()` to `vite.config.ts` beside `reactRouter()`, or list
+`@alxia/react-router` in `ssr.noExternal` and remove it from
+`ssr.external`.
+
 ### `alxia-react-router: … already exists, and reveal leaves it as it is. Run alxia-react-router reveal --force to overwrite it.`
 
 ```text
@@ -888,6 +1114,30 @@ this message too.
 `/pwa/react` from the page alone. The worker and a build script import
 `@alxia/react-router/pwa`, which imports nothing.
 
+### `error: Cannot find package 'isbot' from '…/@alxia/react-router/dist/entry/index.js'`
+
+**When:** a request with a user agent reaches `entry.server.tsx` re-exporting
+`@alxia/react-router/entry` (or a `createEntry()` with no `isBot` option).
+
+```text
+error: Cannot find package 'isbot' from '/app/node_modules/@alxia/react-router/dist/entry/index.js'
+```
+
+**Why:** with no `isBot` option, `/entry` asks `isbot` whether a request
+comes from a crawler, which then gets the whole page, and imports it on the
+first request that needs it. `isbot` and `react-dom` are optional peers of
+the package, so nothing installs them for you. React Router's templates
+install both; an app made another way may not.
+
+**Fix:** add them where the server is built and run:
+
+```sh
+bun add isbot react-dom
+```
+
+Or give the `isBot` option, which replaces the check: `isbot` is then never
+imported, and only `react-dom` is needed.
+
 ### `startWorker(): no precache list. …`
 
 **Why:** the full message ends "Build this worker with `alxia()` from
@@ -1032,6 +1282,265 @@ peers, installed as
 [`Could not resolve: "workbox-core"`](#error-could-not-resolve-workbox-core-maybe-you-need-to-bun-install)
 shows.
 
+### `Cross-site request refused`
+
+**When:** an action reads its body with `readJson` or `readInput` (from
+`jsonActions()`), and the page's post answers 403 with this text.
+
+**Why:** the request carried an `Origin` other than the app's own, or a
+`Sec-Fetch-Site` that is neither `same-origin` nor `none`. That is what a
+post from another site looks like, so it is refused before the body is read.
+The usual honest cause is that the app's origin is not the one the request
+reaches: see [Behind a TLS proxy every action answers 403](#behind-a-tls-proxy-every-action-answers-403).
+
+**Fix:** if the post comes from another site, nothing: the refusal is the
+point. If it comes from your own page, give `jsonActions` the origin your
+users see:
+
+```ts
+export const { readJson } = jsonActions({
+	origin: 'https://app.example.com',
+});
+```
+
+### `Expected a JSON body`
+
+**When:** an action answers 415 with this text.
+
+**Why:** `readJson` takes only `application/json`. A native form post
+(`application/x-www-form-urlencoded` or `multipart/form-data`), a
+`text/plain` body and a request with no content type are refused, since only
+JSON needs a preflight from another site.
+
+**Fix:** post from `useJsonFetcher`, which sets the content type
+(`encType: 'application/json'`), or set `Content-Type: application/json` on
+your own `fetch`. For an action that a native form also posts to before the
+page hydrates, call `requireJsonPost(request)` first: it sends that post back
+to its page, which then posts JSON.
+
+```ts
+const { requireJsonPost, readJson } = jsonActions();
+
+export async function action({ request }: Route.ActionArgs) {
+	requireJsonPost(request);
+	const body = await readJson(request);
+	// …
+}
+```
+
+### `Malformed JSON body`
+
+**When:** an action answers 400 with this text.
+
+**Why:** the request declared `application/json`, but `request.json()` could
+not parse the body: it is empty, truncated, or not JSON at all (a form's
+`FormData` posted with the JSON content type, for example).
+
+**Fix:** post an object through `useJsonFetcher`'s `post(body)`, or
+`JSON.stringify` the body of your own `fetch`. Do not set the content type by
+hand on a `FormData` body.
+
+### `The form sent an input the API would refuse`
+
+**When:** an action that reads its body with `readInput(request, schema)`
+answers 400 with this text.
+
+**Why:** the body was JSON, but its `input` field did not pass the schema: it
+is missing, or one of the checks failed. `readInput` reads `{ input }`, not
+the whole body, and it answers a bare 400 on purpose: the schema is the API's
+own input, so a form that passed its own checks never gets here.
+
+**Fix:** post `{ input: … }`, and make the form's checks the schema's. To see
+what the schema refused while you debug, call it yourself:
+
+```ts
+const body = (await readJson(request)) as { input?: unknown };
+const result = await schema['~standard'].validate(body.input);
+console.log(result.issues);
+```
+
+### `alxia-react-router: the error catalogue (…) was not read`
+
+**When:** the server logs this line (with the error after it, at the level of
+`log.error`) while a language's catalogue is read for the first time, and the
+refusals in that language read in the API's own words.
+
+**Why:** the app's `read(language)` threw: the API was down, slow past its own
+timeout, or answered an error. The catalogue keeps no partial result. It tries
+again once `retryMs` (5 seconds by default) has passed since the failure, on
+the next request that asks for that language; one read is in flight at a time.
+
+**Fix:** read the error that follows the line. Once the API answers, the next
+request after the delay reads the catalogue and the refusals are worded; no
+restart is needed. To see the calls, give `createErrorCatalogue` a `log`
+that records them.
+
+### `alxia-react-router: the error catalogue was not checked, keeping what is held`
+
+**When:** the server logs this line (with the error after it) once a held
+catalogue is older than the TTL and the check of the versions failed.
+
+**Why:** `versions()` threw. The catalogue keeps serving the messages it
+holds, which may be stale, and asks again after `retryMs` instead of after a
+whole TTL.
+
+**Fix:** read the error that follows. Nothing to restart: when the API
+answers, the check goes on and re-reads the languages whose version moved.
+If it repeats while the API is up, check that `versions()` returns a version
+for every language in `languages`: a language missing from its answer is read
+again at each check.
+
+### `alxia-react-router: the error catalogue was not warmed`
+
+**When:** the server logs this line at startup, after `warm()`.
+
+**Why:** `warm()` reads every language without holding the boot back, and
+the promise it started rejected. The reads themselves report their failures
+(`the error catalogue (…) was not read`), so this line means something else
+threw.
+
+**Fix:** read the error that follows. The first request that asks for a
+language reads it anyway, so the server is not left without a catalogue.
+
+### `alxia-react-router: ttlMs threw, using retryMs`
+
+**When:** the server logs this line (with the error after it) each time the
+catalogue reads its TTL and the `ttlMs` getter throws.
+
+**Why:** `ttlMs` is a getter of the app's, such as one that reads a setting,
+and it threw. The catalogue does not let it break a request: it uses
+`retryMs` as the TTL for that read, so the held messages are still served
+and the versions are checked again soon.
+
+**Fix:** read the error that follows and fix the getter, or pass a number.
+
+```ts
+const catalogue = createErrorCatalogue({
+	// …
+	ttlMs: () => settings.catalogueTtlMs ?? 60_000,
+});
+```
+
+### `alxia-react-router: ttlMs is not a duration, using retryMs`
+
+**When:** the server logs this line each time the catalogue reads its TTL and
+`ttlMs` is not a finite number of at least 0: `NaN`, `Infinity`, a negative
+number, or a value that is not a number, such as the string a setting
+returned.
+
+**Why:** a TTL that is not a duration would never expire a held catalogue
+(`Infinity`) or make every comparison false (`NaN`). The catalogue treats it
+like a getter that threw: it uses `retryMs` for that read.
+
+**Fix:** pass a number of milliseconds, converted where the setting is read:
+
+```ts
+const catalogue = createErrorCatalogue({
+	// …
+	ttlMs: () => Number(process.env.CATALOGUE_TTL_MS ?? 60_000),
+});
+```
+
+### `TypeError: createErrorCatalogue(): needs at least one language.`
+
+**When:** the server starts, or the module that calls `createErrorCatalogue`
+is imported.
+
+**Why:** `languages` is empty, usually a list built from an environment
+variable or a config that was not set.
+
+**Fix:** pass the languages the app serves, the same list the page's
+translator knows:
+
+```ts
+const catalogue = createErrorCatalogue({
+	messages: apiMessages,
+	languages: ['en', 'fr'],
+	// …
+});
+```
+
+### `<api>: <operation> (request <id>) answered <status> <code>`
+
+Logged by `apiCallFailure` (a warning for a 4xx, an error for a 5xx), after the
+`api` the app gave it, when the
+API refused a call with a GraphQL body, or answered a status that is passed
+through, such as a 404, which has no `<code>`. For example
+`my-api https://api.example.com/graphql: Todos (request r-1) answered 403 todos.errors.forbidden`.
+
+**Why:** the API answered, and refused: `<status>` and `<code>` are the
+`ApiError`'s. A 4xx is expected (a forbidden page, a missing record), which is
+why it is a warning. The `(request …)` part is there only if the API sent an
+`x-request-id` and your code passed it as `requestId`; without it the line
+carries no id and an error page can show none.
+
+**Fix:** nothing to fix in the package. To find the API's own log line, search
+for the id. To get the id in the line, pass `requestId: requestIdOf(response)`
+from the `fetch` the client calls:
+
+```ts
+import { apiCallFailure, requestIdOf } from '@alxia/react-router/errors';
+
+let requestId: string | undefined;
+const send = async (request: Request) => {
+	const response = await fetch(request);
+	requestId = requestIdOf(response);
+	return response;
+};
+
+export const failed = (error: unknown) =>
+	apiCallFailure(error, { api: 'my-api', requestId });
+```
+
+### `<api>: <operation> (request <id>) answered <status> without GraphQL`
+
+Logged as an error by `apiCallFailure`, and the loader gets a 503 `Response`
+with no body (the reason is in the log).
+
+**Why:** the API, or a gateway in front of it, answered a status that is not
+401, 403 or 404 with a body that is not GraphQL (an HTML 502 page, a 429
+from a rate limiter). The log line's second argument is that body.
+
+**Fix:** read the body in the log and fix the gateway. If a status such as 429
+should reach the page as its own, name it:
+
+```ts
+import { apiCallFailure } from '@alxia/react-router/errors';
+
+export const failed = (error: unknown) =>
+	apiCallFailure(error, {
+		api: 'my-api',
+		passedThrough: new Set([401, 403, 404, 429]),
+	});
+```
+
+### `<api>: <operation> (request <id>) unreachable`, `timeout` or `invalid-response`
+
+Logged as an error by `apiCallFailure`, and the loader gets a 503 `Response`
+with no body (the reason is in the log line).
+
+**Why:** `@nxgt/graphql-client` could not get an answer: `unreachable` is a
+refused connection or a DNS failure, `timeout` is a call past the deadline the
+app gave it, and `invalid-response` is an answer that is no GraphQL response
+(a 2xx with no `data`, garbled JSON). The log line's second argument is the
+cause.
+
+**Fix:** check the API's address and that it is up. For a `timeout`, the call's
+`timeout` option is the app's, not the package's. The 503 reaches the error
+page through `routeError`, which words it with the request id when there is
+one.
+
+### `<api>: <operation> (request <id>) aborted`
+
+Logged as an error by `apiCallFailure`, and the loader gets a 503 `Response`.
+
+**Why:** the `signal` you passed was aborted, so the visitor closed the tab or
+navigated away, and the call failed with whatever error that produced. Nobody
+sees the 503.
+
+**Fix:** none. To keep it out of the logs, test `request.signal.aborted` in
+your own `catch` before calling `apiCallFailure`.
+
 ## Types
 
 ### `Property 'alxia' does not exist on type 'Readonly<RouterContextProvider>'`
@@ -1209,7 +1718,9 @@ error TS2375: Type '{ context: EntryContext; url: string; nonce: string | undefi
 `ServerRouterProps.nonce` is optional without `undefined`. React's
 `nonce` option takes `undefined`, so only the prop complains.
 
-**Fix:** spread the prop in only when there is a nonce:
+**Fix:** use `@alxia/react-router/entry`, whose `handleRequest` does it
+([guide](guide/document.md#the-entry)), or spread the prop in only when
+there is a nonce, in an entry of your own:
 
 ```tsx
 const nonce = nonceOf(loadContext);
@@ -1579,3 +2090,203 @@ cookie never reaches the server. Only the link's query does.
 read it with `manifestLanguage(url, supported, fallback)`; the fallback is a
 supported language the app resolves from the request's `Accept-Language`, not
 from the cookie ([the manifest route](guide/pwa.md#the-web-app-manifest-and-why-the-language-travels-in-lang)).
+
+### A form's own check shows the code (`todos.errors.…`) instead of words
+
+A refinement with `params: { code: 'todos.errors.title-taken' }` shows the
+code itself, or the form library's generic text, where the API's words should
+be.
+
+**Why:** `apiCodeResolver` returns the code unchanged when its `messages`
+store has no text for it in the page's language, and the form library then
+words the issue itself. In the browser the store holds only what the root's
+data brought: the code is not in that list (the app's `clientCodes`), or
+`ApiMessagesProvider` is not around the routes, or it was given another store
+than the resolver's.
+
+**Fix:** add the code to the few the root sends, and wrap the routes with the
+provider on the same instance the resolver reads:
+
+```tsx
+<ApiMessagesProvider messages={apiMessages} value={loaderData.apiMessages}>
+	<Outlet />
+</ApiMessagesProvider>
+```
+
+Check it with `apiMessages.messageOf('fr', code)` in the browser's console
+or a spec ([the catalogue store](guide/errors.md#the-catalogue-store)).
+
+### A message shows its `{braces}`
+
+A refusal reads `{count, plural, one {One item} other {# items}} outside {name}.`
+or `Hello {name}`, braces and all.
+
+**Why:** the `format` given to `createApiMessages` is not an ICU formatter
+(an identity function, a plain `replace`), or a value the message names is
+missing and the formatter handed back the raw message. `apiMessage` returns
+`undefined` for a message the formatter reported to `onError`, but a
+formatter that never calls it returns the text as it found it.
+
+**Fix:** pass the app's ICU formatter, such as `@nxgt/material`'s
+`formatMessage`, and make it call `onError` for a message it cannot format:
+
+```ts
+const apiMessages = createApiMessages<'en' | 'fr'>({ format: formatMessage });
+```
+
+A value is missing when the API's `extensions.params` lacks an argument the
+message names; the same call in a spec shows which.
+
+### A refusal shows the API's raw message
+
+A page shows `Variable "$email" got invalid value …` or another message the
+API worded for developers, instead of the app's words.
+
+**Why:** the error has no API code (a raw `BAD_USER_INPUT`, from a check that
+failed before the API's validation layer), or a code that `isApiCode`
+rejects. Without `refused`, `createApiErrors` says the API's own message for
+such an error.
+
+**Fix:** pass `refused`, the app's generic refusal; it replaces the raw
+message for every error that is not an API code
+([wording a refusal](guide/errors.md#wording-a-refusal)):
+
+```ts
+export const apiErrors = createApiErrors<'en' | 'fr'>({
+	messages: apiMessages,
+	unavailable: (language) => translate('app.error.unavailable', language),
+	refused: (language) => translate('app.error.refused', language),
+});
+```
+
+### `apiRefusal` returns undefined
+
+`apiErrors.apiRefusal(error, language)` gives `undefined` for a call that
+failed, and the action returns nothing useful.
+
+**Why:** the error is neither an API error (`isApiErrorLike`) nor a 503
+`Response`: a network failure, a `TypeError` of the app's own code, a 404.
+`apiRefusal` words only what the API refused or could not be reached for.
+
+**Fix:** rethrow what it does not word, so the route's error boundary shows
+it:
+
+```ts
+const refusal = apiErrors.apiRefusal(error, 'en');
+if (!refusal) throw error;
+```
+
+### The error page shows no request id
+
+The root's `ErrorBoundary` calls `errorRequestId(error)` and gets `undefined`,
+though the API logged the request.
+
+**Why:** `routeError` carries the `requestId` the error already has; it never
+reads it from the network. An `ApiError` has none unless the code that called
+the API set it, and a thrown `Response` is turned into a route error only when
+it has the `x-request-id` header. A loader that returns `routeError(error)`
+instead of throwing it never reaches the boundary at all.
+
+**Fix:** keep the id on the error where the API is called, and `throw` what
+`routeError` gives back
+([loaders and the error page](guide/errors.md#loaders-and-the-error-page)):
+
+```ts
+import { requestIdOf, routeError } from '@alxia/react-router/errors';
+
+// Your own call to the API, declared here as a stub.
+declare function call(): Promise<Response>;
+
+export async function loader() {
+	const response = await call();
+	if (!response.ok) {
+		// A Response of 401, 403, 404 or 503 with the header is a route error.
+		throw routeError(response);
+	}
+	return { requestId: requestIdOf(response) };
+}
+```
+
+### An action shows the error page
+
+An action that calls `fetcherResult`, `fetcherRefusal` or `submitForm` ends on
+the route's error page instead of answering `{ ok: false }` or the form's
+errors.
+
+**Why:** by design, these helpers answer only what the page can word. They
+throw `routeError(error)` for a 401 (the session code redirects to the sign-in
+first), for a failure that is not an API refusal (a network error, a bug of the
+app's own code), and, for `submitForm`, for a 404 that names none of the
+form's fields: the record itself is gone, and no field message could say so.
+
+**Fix:** none is needed for a 401 or a real failure: the error page is the
+right answer. For a 404 that is about a field, name it in `fieldOf`
+(`(path) => (path === 'todo.id' ? 'id' : undefined)`) so it sits under that
+field. For a refusal you would rather word yourself, build on `apiRefusal`,
+which returns `undefined` instead of throwing:
+
+```ts
+const refusal = apiErrors.apiRefusal(error, 'en');
+if (!refusal) throw error;
+return Response.json(
+	{ ok: false, error: refusal.message },
+	{ status: refusal.status },
+);
+```
+
+### Behind a TLS proxy every action answers 403
+
+Every action that reads JSON answers 403 `Cross-site request refused`
+in production, yet works under `react-router dev` and in the specs.
+
+**Why:** `jsonActions()` compares the browser's `Origin` (`https://app.example.com`)
+with the origin of `request.url`. Behind a proxy that terminates TLS the
+app is asked over plain HTTP on an internal host (`http://10.0.0.5:3000`),
+so no post matches. See also
+[`request.url` in a loader is `http://`](#requesturl-in-a-loader-is-http-and-the-internal-host-behind-a-proxy).
+
+**Fix:** name the proxy with `createServer({ proxy: trustProxy(…) })`
+(`trustProxy` is `@alxia/core`'s; see
+[Behind a proxy](guide/customising-the-server.md#behind-a-proxy)). The
+catch-all hands React Router the URL `originalUrl` reads from the trusted
+proxy's `X-Forwarded-Proto` and `X-Forwarded-Host`, so an action's
+`request.url` already carries the public origin and `jsonActions()` needs no
+`origin`. Without a trusted proxy, or when the proxy does not send those
+headers, pass the public origin, as a string or as a getter read at each
+request (so a value set at startup is found):
+
+```ts
+import { jsonActions } from '@alxia/react-router/errors';
+
+export const { readJson, requireJsonPost, readInput } = jsonActions({
+	origin: () => process.env.APP_ORIGIN,
+});
+```
+
+When the getter returns `undefined`, the request's own origin is used, so
+development needs no setting. An empty string is not `undefined`: it is
+kept, and every request with an `Origin` is refused.
+
+### Right after start, refusals read in the API's words
+
+For the first seconds after the server starts, a refusal shows the message
+the API worded (in its default language, say) instead of the page's language.
+It reads right a few seconds later.
+
+**Why:** a language's catalogue is read on first use, and a request waits for
+it only up to `firstReadWaitMs` (1.5 seconds by default), counted from when the
+read started. A slow API, or a failed read, lets the request go on with the
+API's own words; the read carries on in the background (or is retried after
+`retryMs`), and the next request finds it held.
+
+**Fix:** read both languages at startup, so the first request finds them held.
+In `server.ts`:
+
+```ts
+import { catalogue } from './catalogue.server';
+
+catalogue.warm();
+```
+
+Raise `firstReadWaitMs` only if the page should wait longer for the first
+words; it holds every cold request that long when the API hangs.