Request & response

configureServerErrors / reportRequestFailure

Registers the ambient server error hook: called once per error object for every failure the server runtime handles or fails on, with the site that met it; the return value, when given, replaces what the client receives.

Import

import { configureServerErrors, reportRequestFailure } from "@solidjs/web";

`configureServerErrors`

Type signature

function configureServerErrors(config: ServerErrorsConfig): void;

Parameters

`config`

Type: ServerErrorsConfig

`reportRequestFailure`

Reports a failure that fails a request outside any render (see the server entry's reportRequestFailure). Server-only; on the client this is a no-op.

Type signature

function reportRequestFailure(error: unknown, event: RequestEvent): void;

Parameters

`error`

Type: unknown

`event`

Type: RequestEvent

Learn more

`ServerErrorContext`

Where a server-side failure was met, as the server error hook hears it — the client's view of the server entry's type (see configureServerErrors there). kind: "render": fallback/client/failed; kind: "server-function": thrown/channel; kind: "request": failed.

interface ServerErrorContext extends Omit<ServerErrorSite, "event"> {
  event?: RequestEvent;
}

`event`

Type: RequestEvent

`ServerErrorHook`

The server error hook (see configureServerErrors): every failure the server runtime handles or fails on, once per error object, with where it was met. Return the value the client should receive in place of the error — rendered into the fallback, serialized for hydration, sent as the RPC error — or nothing for the default policy (a generic Error outside the dev build, the error itself in it; markSafeError still passes through). A returned value is taken as intended client-facing content and is not sanitized again. Ignored for handling: "failed", which has no wire.

One road a mapping does not reach: a rejected async source's serialized rejection is encoded the moment the source rejects, ahead of the boundary that meets the failure, and carries the default policy's value there. The hydrating client renders from the boundary's record, which carries the mapping; no tick is added to the error path to make the two agree.

type ServerErrorHook = (
  error: unknown,
  context: ServerErrorContext
) => unknown | void;

`ServerErrorsConfig`

interface ServerErrorsConfig {
  onError?: ServerErrorHook;
}

`onError`

Type: ServerErrorHook

`ServerErrorSite`

Where a server failure was met, as the server error hook hears it (see @solidjs/web's ServerErrorContext).

interface ServerErrorSite {
  kind: "render" | "server-function" | "request";
  handling:
    "fallback" | "client" | "failed" | "serialize" | "thrown" | "channel";
  boundary?: string;
  ownerPath?: string[];
  boundaryPath?: string[];
  functionId?: string;
  direct?: boolean;
  event?: unknown;
}