🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
/**
* This is the client-side entrypoint for your tRPC API. It is used to create the `api` object which
* contains the Next.js App-wrapper, as well as your type-safe React Query hooks.
*
* We also create a few inference helpers for input and output types.
*/
import { addBreadcrumb } from "@sentry/nextjs";
import {
httpBatchLink,
httpLink,
loggerLink,
splitLink,
TRPCClientError,
type TRPCClientErrorLike,
type Operation,
type TRPCLink,
} from "@trpc/client";
import { QueryCache } from "@tanstack/react-query";
import { createTRPCNext } from "@trpc/next";
import { type inferRouterInputs, type inferRouterOutputs } from "@trpc/server";
import { observable } from "@trpc/server/observable";
import superjson from "superjson";
import { env } from "@/src/env.mjs";
import type {
ToastOperation,
TrpcToastOperation,
} from "@/src/features/notifications/toastAnalytics";
import { versionUpdateStore } from "@/src/features/version-update/versionUpdateStore";
import { type AppRouter } from "@/src/server/api/root";
import { reportError } from "@/src/utils/reportError";
import { setUpSuperjson } from "@/src/utils/superjson";
import { EXPECTED_TRPC_BAD_REQUEST_PATHS } from "@/src/utils/trpcErrorClassification";
import { trpcErrorToast } from "@/src/utils/trpcErrorToast";
import {
createToastOperationMutationCache,
rememberTrpcToastOperation,
resolveToastOperation,
} from "@/src/utils/trpcToastOperation";
import { isTrpcZodValidationError } from "@/src/utils/trpcValidationError";
export { isTrpcZodValidationError } from "@/src/utils/trpcValidationError";
export { EXPECTED_TRPC_BAD_REQUEST_PATHS } from "@/src/utils/trpcErrorClassification";
setUpSuperjson();
const getBaseUrl = () => {
const hostname = (() => {
if (typeof window !== "undefined") {
return window.location.origin;
}
if (process.env.VERCEL_URL) {
return `https://${process.env.VERCEL_URL}`;
}
return `http://localhost:${process.env.PORT ?? 3000}`;
})();
return `${hostname}${env.NEXT_PUBLIC_BASE_PATH ?? ""}`;
};
// Get current pathname without the base path prefix
// for client-side navigation with a custom basePath set
export const getPathnameWithoutBasePath = () => {
const pathname = window.location.pathname;
const basePath = env.NEXT_PUBLIC_BASE_PATH;
if (basePath && pathname.startsWith(basePath)) {
return pathname.slice(basePath.length) || "/";
}
return pathname;
};
const REPORTED_FAILED_FETCH_MESSAGE = /^failed to fetch(?: \([^)]+\))?$/i;
// Cache to store hashes of recently shown errors (client-side only)
const recentErrorCache = new Set<string>();
const ERROR_DEBOUNCE_MS = 20000;
const hasResponseMeta = (error: TRPCClientError<any>): boolean =>
Boolean((error.meta as { response?: unknown } | undefined)?.response);
const getHttpStatus = (error: unknown): number | undefined =>
error instanceof TRPCClientError && typeof error.data?.httpStatus === "number"
? error.data.httpStatus
: undefined;
const getCause = (error: unknown): unknown =>
error instanceof Error ? error.cause : undefined;
const hasReportedFailedFetchMessage = (error: unknown): boolean => {
if (!(error instanceof Error)) return false;
return REPORTED_FAILED_FETCH_MESSAGE.test(error.message);
};
export const isNetworkConnectivityError = (error: unknown): boolean => {
if (!(error instanceof TRPCClientError)) return false;
// tRPC server errors and infrastructure responses have response metadata.
if (error.data || hasResponseMeta(error)) return false;
const cause = getCause(error);
return (
(cause instanceof TypeError && hasReportedFailedFetchMessage(cause)) ||
hasReportedFailedFetchMessage(error)
);
};
/**
* tRPC error codes that represent EXPECTED, user-facing product states rather
* than actionable application errors:
* - NOT_FOUND — a missing/deleted/never-existed resource (opening a trace
* URL that no longer resolves)
* - FORBIDDEN — the signed-in user may not access this resource (a trace in
* another org, a project they are not a member of)
* - UNAUTHORIZED — the session expired or the user is not signed in
* - UNPROCESSABLE_CONTENT — a resource guardrail rejected the request with
* user-facing advice. The server mints this code only for
* query resource limits (`ClickHouseResourceError` → "narrow
* your request…", see `withErrorHandling` in
* `web/src/server/api/trpc.ts`) and oversized payloads
* (`PayloadTooLargeError`, httpCode 422)
*
* The UI already renders each of these as an error page or toast — it is the
* product working as designed, not a regression a human should act on. Sending
* them to Sentry turns the error tracker into a log of ordinary navigation
* (`Trace not found` alone is the #2 issue by volume, ~30k events / ~3.3k
* users; the query-guardrail advice minted ~2.3k events / ~600 users in two
* weeks) and drowns real signal.
*
* Suppressing capture here does NOT blind us to real authz/lookup regressions:
* the server owns that signal — a genuine regression surfaces as a 4xx-rate
* anomaly server-side and as user reports, whereas the client Sentry event is
* only an amplified, lower-fidelity copy. The server itself already logs
* NOT_FOUND / UNAUTHORIZED as non-errors and every guardrail hit as a warning
* (`web/src/server/api/trpc.ts`), and `handleTrpcError` leaves a breadcrumb
* for each suppressed error so its path + code stay in the trail of any real
* event captured later in the session.
*
* Deliberately narrow: only these codes on an actual `TRPCClientError`, plus
* Zod input validation (`BAD_REQUEST` whose message is a Zod 4 issue list or
* whose `data.zodError` is populated), plus CONFLICT on
* {@link EXPECTED_TRPC_CONFLICT_PATHS}, plus BAD_REQUEST on
* {@link EXPECTED_TRPC_BAD_REQUEST_PATHS}. Empty/too-short fields, stale
* in-app-agent approvals, and a rejected user-configured remote-experiment
* URL are the product working as designed — the toast is the UX; Sentry
* must not log them.
* A 5xx (`INTERNAL_SERVER_ERROR`), a non-Zod `BAD_REQUEST` outside the
* allowlist, a CONFLICT outside the allowlist, an unrecognized code, or
* any non-tRPC error is not expected and keeps flowing to Sentry.
*/
export const EXPECTED_TRPC_ERROR_CODES = [
"NOT_FOUND",
"FORBIDDEN",
"UNAUTHORIZED",
"UNPROCESSABLE_CONTENT",
] as const;
/**
* CONFLICT is usually a uniqueness / concurrency failure we still want
* (duplicate names, unique-constraint races). These procedures throw 409
* only as an optimistic-concurrency / stale-UI race the product already
* toasts — expected user-facing state, not a regression.
*
* `inAppAgent.decideToolApproval` is the only current member: every CONFLICT
* it throws means the parent run is no longer AWAITING_APPROVAL (already
* decided, expired, or cancelled). The UI already tells the user to reload.
*/
export const EXPECTED_TRPC_CONFLICT_PATHS = [
"inAppAgent.decideToolApproval",
] as const;
const getTrpcErrorData = (
error: unknown,
): { code?: unknown; path?: unknown } | undefined =>
error instanceof TRPCClientError
? (error.data as { code?: unknown; path?: unknown } | undefined)
: undefined;
/** The tRPC error code (`data.code`) when `error` is a TRPCClientError. */
export const getTrpcErrorCode = (error: unknown): string | undefined => {
const code = getTrpcErrorData(error)?.code;
return typeof code === "string" ? code : undefined;
};
/** The tRPC procedure path (`data.path`) when available — used as a Sentry tag. */
export const getTrpcErrorPath = (error: unknown): string | undefined => {
const path = getTrpcErrorData(error)?.path;
return typeof path === "string" ? path : undefined;
};
/**
* Sentry fingerprint for a captured tRPC client error.
*
* Sentry's default grouping keys on the stack trace, and every
* `TRPCClientError` throws from the same client-link frames — so unrelated
* failures (different procedures, different codes, different messages)
* collapse into one mega-issue. Grouping by code + procedure path gives each
* distinct failure class its own issue with bounded cardinality
* (procedures × codes) and no user data: `data.path` is the static procedure
* name from the router definition (e.g. `traces.deleteMany`) — query input,
* ids, and messages are never part of it.
*/
export const getTrpcErrorFingerprint = (error: unknown): string[] => [
"trpc-client-error",
getTrpcErrorCode(error) ?? "unknown",
getTrpcErrorPath(error) ?? "unknown",
];
/**
* True when `error` is a TRPCClientError whose code is an EXPECTED, user-facing
* state that should not be captured to Sentry.
* See {@link EXPECTED_TRPC_ERROR_CODES}, {@link EXPECTED_TRPC_CONFLICT_PATHS},
* and {@link EXPECTED_TRPC_BAD_REQUEST_PATHS}.
*/
export const isExpectedTrpcClientError = (error: unknown): boolean => {
const code = getTrpcErrorCode(error);
if (
code !== undefined &&
(EXPECTED_TRPC_ERROR_CODES as readonly string[]).includes(code)
) {
return true;
}
const path = getTrpcErrorPath(error);
if (
code === "CONFLICT" &&
path !== undefined &&
(EXPECTED_TRPC_CONFLICT_PATHS as readonly string[]).includes(path)
) {
return true;
}
if (
code === "BAD_REQUEST" &&
path !== undefined &&
(EXPECTED_TRPC_BAD_REQUEST_PATHS as readonly string[]).includes(path)
) {
return true;
}
return isTrpcZodValidationError(error);
};
// HTTP statuses returned when a request's URL/headers are too large for the
// browser or an upstream proxy. The response body is usually not a tRPC
// envelope, so these are otherwise hard to diagnose.
const REQUEST_TOO_LARGE_STATUSES = [414, 431];
type SyntaxErrorWithResponseStatus = SyntaxError & { responseStatus?: number };
/**
* `@trpc/client` (11.13.4) rejects with the bare `SyntaxError` when
* JSON-parsing a response body fails — the link only records the response
* meta (and so the HTTP status) for fulfilled requests. This fetch wrapper
* re-attaches the status to the parse `SyntaxError` so error classification
* can tell an app-owned 414/431 failure from transport garbage.
* Exported for tests.
*/
export const fetchWithParseErrorStatus: typeof fetch = async (input, init) => {
const response = await fetch(input, init);
const originalJson = response.json.bind(response);
response.json = async () => {
try {
return await originalJson();
} catch (error) {
if (error instanceof SyntaxError) {
(error as SyntaxErrorWithResponseStatus).responseStatus =
response.status;
}
throw error;
}
};
return response;
};
/** HTTP status of a failed tRPC response: from the annotated parse error
* (`fetchWithParseErrorStatus`) or, when a link attached it, the response meta. */
const getResponseStatus = (error: TRPCClientError<any>): number | undefined => {
const cause = getCause(error);
if (
cause instanceof SyntaxError &&
typeof (cause as SyntaxErrorWithResponseStatus).responseStatus === "number"
) {
return (cause as SyntaxErrorWithResponseStatus).responseStatus;
}
return error.meta?.response instanceof Response
? error.meta.response.status
: undefined;
};
/**
* True when `error` is a TRPCClientError caused by the tRPC client failing to
* JSON-parse the HTTP response body (a `SyntaxError` cause, e.g. "JSON.parse:
* unexpected character at line 1 column 1 of the JSON data" / "Unexpected end
* of JSON input").
*
* Our tRPC handler always returns JSON, so a non-JSON body means something
* between server and client replaced or truncated it (a proxy/LB error page,
* an interrupted connection, an intercepting proxy). That is transport state,
* not an app bug — the server owns the real signal. A parsed tRPC error
* envelope (`error.data`) means the server DID answer with a real error
* shape; those keep flowing to Sentry unchanged.
*
* Deliberately NOT matched: a parse failure on HTTP 414/431. That is the
* app-owned oversized-GET-URL bug class (see `sendAsPostOption`) and must
* keep capturing. Unknown status (no annotation, no meta) stays classified
* as transport — the live client drops the response meta on parse failures,
* which is why `fetchWithParseErrorStatus` exists.
*/
export const isTrpcResponseParseError = (error: unknown): boolean => {
if (!(error instanceof TRPCClientError)) return false;
if (error.data) return false;
if (!(getCause(error) instanceof SyntaxError)) return false;
const status = getResponseStatus(error);
return status === undefined || !REQUEST_TOO_LARGE_STATUSES.includes(status);
};
/**
* Soft cap for a tRPC GET URL. The request head (URL line + cookies + headers)
* is capped at ~16KB by Node and most proxies; cookies (NextAuth JWT, PostHog)
* commonly consume several KB, so the serialized query URL must stay well
* below that. Numerically similar to the page-URL filter budget
* (`MAX_URL_FILTER_QUERY_LENGTH`) but independent of it: this bounds the full
* tRPC GET URL (path + superjson-serialized input), not the `?filter=` param.
* Queries whose GET URL would exceed this are sent as POST.
*/
export const MAX_TRPC_GET_URL_BYTES = 4_000;
/** Approximate GET URL size for a tRPC query, matching the live httpLink encoding. */
export const getApproxTrpcGetUrlBytes = (
path: string,
input: unknown,
): number => {
const encodedInput = encodeURIComponent(
JSON.stringify(superjson.serialize(input)),
);
return `${getBaseUrl()}/api/trpc/${path}?input=`.length + encodedInput.length;
};
/**
* tRPC serializes query input into the GET URL. For reads whose input scales with
* the number of rows (the `*.batchIO` I/O fetches) or with filter cardinality
* (a wide `none of [userIds]` selection kept in session storage, a page of
* `traceIds` on `traces.metrics`), that URL grows large (~6KB at 50 rows, ~12KB
* at 100) and — together with per-user cookies (NextAuth session JWT, PostHog,
* ...) — can exceed the request line/header budget enforced by browsers and
* reverse proxies, failing with HTTP 414 (URI Too Long) or 431 (Request Header
* Fields Too Large). Because cookie size varies per user, it reproduces for some
* and not others.
*
* A query is sent as POST (payload in the body, URL stays small) when:
* - the call site opts in via the `sendAsPost` context flag: merge
* `sendAsPostOption` into its query options, e.g.
* `useQuery(input, { ...sendAsPostOption, enabled })`, or
* - the serialized GET URL would exceed `MAX_TRPC_GET_URL_BYTES`.
* The server accepts query-over-POST via `allowMethodOverride` (see
* src/pages/api/trpc/[trpc].ts); mutations stay POST-only.
*/
export const sendAsPostOption = {
trpc: { context: { sendAsPost: true } },
} as const;
export const shouldSendQueryAsPost = (
op: Pick<Operation, "type" | "path" | "input" | "context">,
): boolean => {
if (op.context.sendAsPost === true) return true;
if (op.type !== "query") return false;
try {
return getApproxTrpcGetUrlBytes(op.path, op.input) > MAX_TRPC_GET_URL_BYTES;
} catch {
// If we cannot size the input, leave routing unchanged (GET for queries).
return false;
}
};
const trpcApiUrl = () => `${getBaseUrl()}/api/trpc`;
const postOverrideHttpLink = () =>
httpLink({
url: trpcApiUrl(),
transformer: superjson,
methodOverride: "POST",
fetch: fetchWithParseErrorStatus,
});
/**
* Creates a unique hash for an error to track it for debouncing; implementation hashes based on the tRPC path and http status
*/
const getErrorHash = (error: unknown): string => {
if (error instanceof TRPCClientError) {
const path = (error.data as { path?: string })?.path;
const code = error.data?.httpStatus;
if (path && code) return `${path}::${code}`;
}
if (error instanceof Error) {
return `error::${error.message}`;
}
return "unknown_error::";
};
/**
* Checks if a toast should be shown for a given error and managed debouncing logic.
* @returns `true` if a toast should be shown, `false` if it should be suppressed.
*/
const shouldShowToast = (error: unknown): boolean => {
if (typeof window === "undefined") return true;
const errorHash = getErrorHash(error);
if (recentErrorCache.has(errorHash)) {
return false;
}
recentErrorCache.add(errorHash);
// Set a timer to remove error hash from cache after the debounce period
setTimeout(() => {
recentErrorCache.delete(errorHash);
}, ERROR_DEBOUNCE_MS);
return true;
};
const handleTrpcError = (
error: unknown,
operation: ToastOperation,
shouldSilenceError = false,
) => {
if (error instanceof TRPCClientError) {
const httpStatus: number =
typeof error.data?.httpStatus === "number" ? error.data.httpStatus : 500;
// Version mismatch UX is owned by VersionUpdateBanner (fed by
// buildIdLink / versionUpdateStore). 400/404 here are real API errors.
if (isExpectedTrpcClientError(error)) {
// Expected, user-facing states (a missing/forbidden resource, an expired
// session) are the product working as designed — don't mint a Sentry
// issue for them. Leave a breadcrumb so the path + code stay in the trail
// of any real event captured later this session; the server owns the real
// authz/lookup-regression signal. See `isExpectedTrpcClientError`.
addBreadcrumb({
category: "trpc",
type: "http",
level: "info",
message: "Suppressed expected tRPC error (not sent to Sentry)",
data: {
code: getTrpcErrorCode(error),
path: getTrpcErrorPath(error),
httpStatus,
},
});
} else if (isTrpcResponseParseError(error)) {
// The response body was not JSON (proxy error page, truncated body) —
// transport state, not an app bug. Breadcrumb instead of capture; the
// toast below still renders. See `isTrpcResponseParseError`.
addBreadcrumb({
category: "trpc",
type: "http",
level: "warning",
message: "Suppressed tRPC response parse error (not sent to Sentry)",
data: {
message: error.message,
status: getResponseStatus(error),
},
});
} else {
// Real tRPC errors keep flowing to Sentry, tagged and fingerprinted by
// procedure/code so each failure class gets its own issue instead of
// collapsing into one opaque bucket (see getTrpcErrorFingerprint).
reportError(error, {
area: "trpc",
fingerprint: getTrpcErrorFingerprint(error),
tags: {
"trpc.code": getTrpcErrorCode(error),
"trpc.path": getTrpcErrorPath(error),
},
});
}
} else if (shouldSilenceError) {
// A silenced non-tRPC query error — the surface owns the error UX
// end-to-end (meta silentAllErrors, e.g. the SSE dashboard transport:
// stall aborts and stream failures render inline per widget, and genuine
// server failures are logged server-side). Breadcrumb, not capture.
addBreadcrumb({
category: "trpc",
type: "http",
level: "warning",
message: "Suppressed silenced non-tRPC query error (not sent to Sentry)",
data: {
message: error instanceof Error ? error.message : String(error),
},
});
} else {
// For non-TRPC errors, still send to Sentry (coerced to a real Error).
reportError(error, { area: "trpc" });
}
if (!shouldSilenceError && shouldShowToast(error)) {
trpcErrorToast(error, operation);
}
};
/**
* Error handler for `mutateAsync` catch blocks whose mutation KEEPS the
* react-query default `onError`: the seam (`handleTrpcError`) already
* classified, captured, and toasted the tRPC failure, so the catch only needs
* to swallow the rejection — a `console.error` there would mint a second,
* unclassified Sentry event via `captureConsoleIntegration`. Non-tRPC errors
* (thrown by the catch's own post-success work: callbacks, router.push, ...)
* were NOT seen by the seam and are reported with the caller's `area`.
*/
export const reportNonTrpcError = (
error: unknown,
area: string,
extra?: Record<string, unknown>,
): void => {
if (error instanceof TRPCClientError) return;
reportError(error, { area, extra });
};
/**
* Error handler for `mutateAsync` catch blocks whose mutation defines a local
* `onError` (which REPLACES the react-query default): nothing classified or
* captured the failure, so route it through the seam here — with the standard
* error toast silenced, since the local `onError` owns the UX (form errors,
* custom toasts). Replaces the `console.error(error)` anti-pattern, which
* minted unclassified Sentry events via `captureConsoleIntegration`.
* Non-tRPC errors (thrown by the catch's own post-success work) were never a
* tRPC failure, so they are reported with the caller's `area` — mirroring
* `reportNonTrpcError` — instead of the seam's generic `trpc` area.
*/
export const reportTrpcErrorWithoutToast = (
error: unknown,
area: string,
): void => {
if (error instanceof TRPCClientError) {
handleTrpcError(
error,
resolveToastOperation(error, undefined, "mutation.execute"),
true,
);
return;
}
reportError(error, { area });
};
// Reads the `x-build-id` response header (the build id serving this response)
// and feeds the version-update store that drives VersionUpdateBanner
// (see src/features/version-update). Called on EVERY response — success
// and error — so a mismatch is detected on the first response after a deploy,
// not only when a stale chunk 404s. Exported so tests can inject an observed
// build id without going through the tRPC link.
export const captureBuildId = (response: unknown) => {
if (!(response instanceof Response)) return;
const observed = response.headers.get("x-build-id");
if (!observed) return;
versionUpdateStore.reportObservedBuildId(observed);
};
// Track the build id serving tRPC responses to compare against the running one.
export const buildIdLink = (): TRPCLink<AppRouter> => () => {
return ({ next, op }) => {
return observable((observer) => {
const unsubscribe = next(op).subscribe({
next(value) {
captureBuildId(value.context?.response);
observer.next(value);
},
error(err) {
captureBuildId(
err.meta && err.meta.response ? err.meta.response : undefined,
);
// `op.path` comes from the typed AppRouter operation, not from the
// response body. Record it before React Query and local handlers see
// the error so transport and pathless failures retain their origin.
rememberTrpcToastOperation(err, op.path as TrpcToastOperation);
observer.error(err);
},
complete() {
observer.complete();
},
});
return unsubscribe;
});
};
};
// Logs request-size context to the console when a GET-routed query fails because
// its URL was too large. tRPC serializes query input into the GET URL, so an
// oversized input (a long list, a wide filter selection, ...) can trip HTTP 414
// (URI Too Long) or 431 (Request Header Fields Too Large). Surfacing the path and
// approximate URL size makes such failures diagnosable from a console screenshot
// and points at the fix (send the query as POST). Queries already routed as POST
// (`sendAsPost` or auto-oversized) and mutations are skipped.
const requestTooLargeDiagnosticsLink = (): TRPCLink<AppRouter> => () => {
return ({ next, op }) => {
return observable((observer) => {
const unsubscribe = next(op).subscribe({
next(value) {
observer.next(value);
},
error(err) {
const sentAsGet = op.type === "query" && !shouldSendQueryAsPost(op);
// Annotation-first (meta is dropped on JSON-parse failures — the
// common shape of a real 414/431, whose body is empty/HTML).
const status = getResponseStatus(err);
if (
sentAsGet &&
status !== undefined &&
REQUEST_TOO_LARGE_STATUSES.includes(status)
) {
try {
const approxUrlBytes = getApproxTrpcGetUrlBytes(
op.path,
op.input,
);
// Keep the format string constant (no interpolation) and pass the
// dynamic values as a structured argument — they remain visible and
// expandable in the console without risking format-string injection.
console.error(
"[tRPC] a query sent as GET failed because the request URL was " +
"too large (HTTP 414/431). Large query inputs should be sent as " +
"POST — add { ...sendAsPostOption } to the query's options (see " +
"sendAsPostOption in src/utils/api.ts).",
{ path: op.path, status, approxUrlBytes },
);
} catch {
// diagnostics only — never throw from the logging path
}
}
observer.error(err);
},
complete() {
observer.complete();
},
});
return unsubscribe;
});
};
};
const shouldSilenceError = (
meta: Record<string, unknown>,
error: Error,
): boolean => {
if (isNetworkConnectivityError(error)) {
return true;
}
// For queries whose surface owns the error UX entirely (e.g. a widget's
// inline error state) — non-HTTP errors carry no status to match against.
if (meta?.silentAllErrors === true) {
return true;
}
if (Array.isArray(meta?.silentHttpCodes)) {
const httpStatus = getHttpStatus(error);
return (
httpStatus !== undefined && meta.silentHttpCodes.includes(httpStatus)
);
}
return false;
};
/**
* Default retry policy for tRPC queries.
*
* Don't retry on 404s: a deleted/missing resource never appears via retry, so
* failing fast avoids piling up pointless refetches (and ClickHouse load for
* resources backed by it).
*
* Don't retry on 422s either: the server mints UNPROCESSABLE_CONTENT only for
* query resource guardrails (`ClickHouseResourceError`) and oversized payloads
* (see {@link EXPECTED_TRPC_ERROR_CODES}). A retry re-runs the same over-budget
* query while ClickHouse is still saturated — self-hosted ClickHouse keeps
* executing the abandoned attempt (`cancel_http_readonly_queries_on_client_close`
* defaults to 0 outside ClickHouse Cloud) — so each rejection would multiply
* the load that caused it.
*
* Every other 4xx keeps the default retry/backoff — some (e.g. a route param
* that hasn't hydrated yet, a proxy-level 429) are transient and self-heal.
*/
export const shouldRetryQuery = (
failureCount: number,
error: unknown,
): boolean => {
const httpStatus = getHttpStatus(error);
if (httpStatus === 404 || httpStatus === 422) {
return false;
}
return failureCount < 3;
};
/**
* Retry policy for single-resource detail queries (trace, session): also fails
* fast on 401 so the page can render its access error immediately. Use this
* instead of a hand-written `retry` so the {@link shouldRetryQuery} rules still
* apply — a per-query `retry` replaces the default rather than extending it.
*/
export const shouldRetryResourceQuery = (
failureCount: number,
error: unknown,
): boolean =>
getHttpStatus(error) !== 401 && shouldRetryQuery(failureCount, error);
/** APIError is returned by api.*.*.useQuery */
export type APIError = TRPCClientErrorLike<AppRouter>;
/** A set of type-safe react-query hooks for your tRPC API. */
export const api = createTRPCNext<AppRouter>({
config() {
return {
/**
* Links used to determine request flow from client to server.
*
* @see https://trpc.io/docs/links
*/
links: [
buildIdLink(),
requestTooLargeDiagnosticsLink(),
loggerLink({
// Only enable in development - production logs would be captured by Sentry
// in an unreadable format. We handle 5xx errors via reportError in
// handleTrpcError and use DataDog for additional server-side logging.
enabled: () => process.env.NODE_ENV === "development",
}),
splitLink({
condition(op) {
// check for context property `skipBatch`
const skipBatch = op.context.skipBatch === true;
// Manually skip batching, perf experiment
const alwaysSkipBatch = true;
return skipBatch || alwaysSkipBatch;
},
// when condition is true, use normal request. Route oversized queries
// through POST so their payload does not inflate the GET URL and trip
// HTTP 414/431. See `shouldSendQueryAsPost`.
true: splitLink({
condition: shouldSendQueryAsPost,
true: postOverrideHttpLink(),
false: httpLink({
url: trpcApiUrl(),
transformer: superjson,
fetch: fetchWithParseErrorStatus,
}),
}),
// when condition is false, use batching
false: httpBatchLink({
url: trpcApiUrl(),
transformer: superjson,
maxURLLength: 2083, // avoid too large batches
fetch: fetchWithParseErrorStatus,
}),
}),
],
queryClientConfig: {
defaultOptions: {
queries: {
// react query defaults to `online`, but we want to disable it as it caused issues for some users
networkMode: "always",
retry: shouldRetryQuery,
},
mutations: {
onError: (error) =>
handleTrpcError(
error,
resolveToastOperation(error, undefined, "mutation.execute"),
),
// react query defaults to `online`, but we want to disable it as it caused issues for some users
networkMode: "always",
},
},
queryCache: new QueryCache({
onError: (error, query) => {
handleTrpcError(
error,
resolveToastOperation(error, query.meta, "query.execute"),
shouldSilenceError(query.meta ?? {}, error),
);
},
}),
mutationCache: createToastOperationMutationCache(),
},
};
},
/**
* Whether tRPC should await queries when server rendering pages.
*
* @see https://trpc.io/docs/nextjs#ssr-boolean-default-false
*/
ssr: false,
transformer: superjson, // since tRPC v11 has to be here for some reason
});
/**
* Inference helper for inputs.
*
* @example type HelloInput = RouterInputs['example']['hello']
*/
export type RouterInputs = inferRouterInputs<AppRouter>;
/**
* Inference helper for outputs.
*
* @example type HelloOutput = RouterOutputs['example']['hello']
*/
export type RouterOutputs = inferRouterOutputs<AppRouter>;