Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(web): send oversized tRPC queries as POST to avoid HTTP 414/431 (#16268)

Nikita Kabardin4360ee2cc995
diff --git a/web/src/pages/api/trpc/[trpc].ts b/web/src/pages/api/trpc/[trpc].ts
index b790a08385..573a253926 100644
--- a/web/src/pages/api/trpc/[trpc].ts
+++ b/web/src/pages/api/trpc/[trpc].ts
@@ -18,13 +18,12 @@ export const config = {
export default createNextApiHandler({
router: appRouter,
createContext: createTRPCContext,
- // Allow queries to be sent as POST. The client only does this for the
- // `*.batchIO` I/O queries, whose per-row payload would otherwise inflate the
- // GET URL and trip HTTP 431 (queries opt in via the `sendAsPost` context flag;
- // see `sendAsPostOption` in src/utils/api.ts). This flag is handler-wide (tRPC
- // has no per-procedure option), but it only widens the accepted method for
- // queries (read-only); mutations remain POST-only, so the GET-mutation
- // protection is unchanged.
+ // Allow queries to be sent as POST. The client does this for `*.batchIO`
+ // I/O queries (opt-in via `sendAsPostOption`) and for any query whose
+ // serialized GET URL would exceed `MAX_TRPC_GET_URL_BYTES` (wide filters,
+ // per-row id lists). This flag is handler-wide (tRPC has no per-procedure
+ // option), but it only widens the accepted method for queries (read-only);
+ // mutations remain POST-only, so the GET-mutation protection is unchanged.
allowMethodOverride: true,
onError: ({ path, error }) => {
const { logLevel, shouldTrace } = getTRPCErrorReporting(error);
diff --git a/web/src/utils/api.clienttest.ts b/web/src/utils/api.clienttest.ts
index 8b39e14dd6..47b71e26d7 100644
--- a/web/src/utils/api.clienttest.ts
+++ b/web/src/utils/api.clienttest.ts
@@ -6,6 +6,7 @@ import {
EXPECTED_TRPC_ERROR_CODES,
captureBuildId,
fetchWithParseErrorStatus,
+ getApproxTrpcGetUrlBytes,
getTrpcErrorCode,
getTrpcErrorFingerprint,
getTrpcErrorPath,
@@ -13,8 +14,10 @@ import {
isNetworkConnectivityError,
isTrpcResponseParseError,
isTrpcZodValidationError,
+ MAX_TRPC_GET_URL_BYTES,
reportNonTrpcError,
reportTrpcErrorWithoutToast,
+ shouldSendQueryAsPost,
} from "@/src/utils/api";
const {
@@ -233,6 +236,98 @@ describe("isTrpcResponseParseError", () => {
});
});
+describe("shouldSendQueryAsPost", () => {
+ const queryOp = (
+ input: unknown,
+ context: Record<string, unknown> = {},
+ path = "traces.all",
+ ) => ({
+ type: "query" as const,
+ path,
+ input,
+ context,
+ });
+
+ it("keeps small queries on GET", () => {
+ expect(
+ shouldSendQueryAsPost(
+ queryOp({ projectId: "proj_1", filter: [], page: 0, limit: 50 }),
+ ),
+ ).toBe(false);
+ });
+
+ it("honors the explicit sendAsPost context flag", () => {
+ expect(
+ shouldSendQueryAsPost(
+ queryOp({ projectId: "proj_1" }, { sendAsPost: true }),
+ ),
+ ).toBe(true);
+ });
+
+ it("routes a traces.all query whose filter would blow the GET URL as POST", () => {
+ // Session-storage-only filter states can exceed the page-URL budget
+ // (MAX_URL_FILTER_QUERY_LENGTH) and still be sent as tRPC input. ~200
+ // user IDs is the shape that 431s the GET request line.
+ const input = {
+ projectId: "proj_1",
+ filter: [
+ {
+ column: "userId",
+ type: "stringOptions",
+ operator: "none of",
+ value: Array.from(
+ { length: 200 },
+ (_, i) => `user-${i}-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`,
+ ),
+ },
+ ],
+ page: 0,
+ limit: 50,
+ };
+
+ expect(getApproxTrpcGetUrlBytes("traces.all", input)).toBeGreaterThan(
+ MAX_TRPC_GET_URL_BYTES,
+ );
+ // Auto-routing does not set `sendAsPost` on the op; the 414/431 diagnostic
+ // must use `shouldSendQueryAsPost`, not the explicit flag alone.
+ const op = queryOp(input);
+ expect(op.context.sendAsPost).not.toBe(true);
+ expect(shouldSendQueryAsPost(op)).toBe(true);
+ });
+
+ it("routes a traces.metrics query whose id list would blow the GET URL as POST", () => {
+ const input = {
+ projectId: "proj_1",
+ filter: [],
+ traceIds: Array.from(
+ { length: 100 },
+ (_, i) => `trace-${i.toString().padStart(3, "0")}-${"x".repeat(36)}`,
+ ),
+ };
+
+ expect(getApproxTrpcGetUrlBytes("traces.metrics", input)).toBeGreaterThan(
+ MAX_TRPC_GET_URL_BYTES,
+ );
+ expect(shouldSendQueryAsPost(queryOp(input, {}, "traces.metrics"))).toBe(
+ true,
+ );
+ });
+
+ it("does not force mutations onto the methodOverride POST link", () => {
+ expect(
+ shouldSendQueryAsPost({
+ type: "mutation",
+ path: "traces.deleteMany",
+ input: {
+ projectId: "proj_1",
+ traceIds: Array.from({ length: 200 }, (_, i) => `t-${i}`),
+ },
+ context: {},
+ }),
+ ).toBe(false);
+ });
+});
+
describe("fetchWithParseErrorStatus", () => {
afterEach(() => {
vi.unstubAllGlobals();
diff --git a/web/src/utils/api.ts b/web/src/utils/api.ts
index 2855ae567f..c33ff3bee4 100644
--- a/web/src/utils/api.ts
+++ b/web/src/utils/api.ts
@@ -267,18 +267,44 @@ export const isTrpcResponseParseError = (error: unknown): boolean => {
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), 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 431 (Request Header Fields Too
- * Large). Because cookie size varies per user, it reproduces for some and not
- * others.
+ * 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 opts into being sent as POST (payload in the body, URL stays small) by
- * setting the `sendAsPost` context flag at the call site: merge `sendAsPostOption`
- * into its query options, e.g. `useQuery(input, { ...sendAsPostOption, enabled })`.
+ * 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.
*/
@@ -286,8 +312,28 @@ export const sendAsPostOption = {
trpc: { context: { sendAsPost: true } },
} as const;
-const shouldSendQueryAsPost = (op: Operation): boolean =>
- op.context.sendAsPost === true;
+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
@@ -474,8 +520,8 @@ const buildIdLink = (): TRPCLink<AppRouter> => () => {
// 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). `*.batchIO` and mutations are
-// already POST, so the URL is not the culprit for them and they are skipped.
+// 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) => {
@@ -484,8 +530,7 @@ const requestTooLargeDiagnosticsLink = (): TRPCLink<AppRouter> => () => {
observer.next(value);
},
error(err) {
- const sentAsGet =
- op.type === "query" && op.context.sendAsPost !== true;
+ 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);
@@ -496,12 +541,10 @@ const requestTooLargeDiagnosticsLink = (): TRPCLink<AppRouter> => () => {
REQUEST_TOO_LARGE_STATUSES.includes(status)
) {
try {
- const encodedInput = encodeURIComponent(
- JSON.stringify(superjson.serialize(op.input)),
+ const approxUrlBytes = getApproxTrpcGetUrlBytes(
+ op.path,
+ op.input,
);
- const approxUrlBytes =
- `${getBaseUrl()}/api/trpc/${op.path}?input=`.length +
- encodedInput.length;
// 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.
@@ -576,26 +619,21 @@ export const api = createTRPCNext<AppRouter>({
return skipBatch || alwaysSkipBatch;
},
- // when condition is true, use normal request. Route the oversized
- // `*.batchIO` queries through POST so their per-row payload does not
- // inflate the GET URL and trip HTTP 431. See `shouldSendQueryAsPost`.
+ // 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: httpLink({
- url: `${getBaseUrl()}/api/trpc`,
- transformer: superjson,
- methodOverride: "POST",
- fetch: fetchWithParseErrorStatus,
- }),
+ true: postOverrideHttpLink(),
false: httpLink({
- url: `${getBaseUrl()}/api/trpc`,
+ url: trpcApiUrl(),
transformer: superjson,
fetch: fetchWithParseErrorStatus,
}),
}),
// when condition is false, use batching
false: httpBatchLink({
- url: `${getBaseUrl()}/api/trpc`,
+ url: trpcApiUrl(),
transformer: superjson,
maxURLLength: 2083, // avoid too large batches
fetch: fetchWithParseErrorStatus,
@@ -654,10 +692,15 @@ export const directApi = createTRPCProxyClient<AppRouter>({
// handleTrpcError and use DataDog for additional server-side logging.
enabled: () => process.env.NODE_ENV === "development",
}),
- httpBatchLink({
- url: `${getBaseUrl()}/api/trpc`,
- transformer: superjson,
- maxURLLength: 2083, // avoid too large batches
+ splitLink({
+ condition: shouldSendQueryAsPost,
+ true: postOverrideHttpLink(),
+ false: httpBatchLink({
+ url: trpcApiUrl(),
+ transformer: superjson,
+ maxURLLength: 2083, // avoid too large batches
+ fetch: fetchWithParseErrorStatus,
+ }),
}),
],
});