refactor(qwik-router): lean the major — extract isServerError and the submit-rejection contract

maiieul · maiieul · commit 8e662a62ef89 · 2026-06-12T18:19:04.000+02:00
isServerError (minor) and always-reject-on-abort (patch) move to
follow-up PRs for a separate release. Interim abort contract: a
programmatic submit() rejects; &lt;Form&gt; surfaces aborts via
submitcompleted detail.aborted. The ServerError reserved-key hardening
stays (patch changeset).
diff --git a/.changeset/is-server-error-guard.md b/.changeset/is-server-error-guard.md
diff --git a/.changeset/server-error-reserved-keys.md b/.changeset/server-error-reserved-keys.md
@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': patch
+---
+
+`ServerError` no longer flattens reserved payload keys (`message`, `status`, `data`, ...) onto the error — `error.message` is always a string and payloads can't clobber `Error` internals.
diff --git a/.changeset/submit-rejects-servererror-hardening.md b/.changeset/submit-rejects-servererror-hardening.md
diff --git a/e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/actions/abort/index.tsx b/e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/actions/abort/index.tsx
@@ -1,5 +1,5 @@
 import { component$, useSignal } from '@qwik.dev/core';
-import { Form, isServerError, routeAction$, useLocation } from '@qwik.dev/router';
+import { Form, routeAction$, useLocation } from '@qwik.dev/router';
 
 export const useAbortAction = routeAction$((form, ev) => {
   if (form.boom) {
@@ -22,7 +22,8 @@ export default component$(() => {
             await action.submit({ boom: true });
             caught.value = 'resolved';
           } catch (err) {
-            caught.value = isServerError(err) ? `caught:${err.status}` : 'caught:unknown';
+            const status = err instanceof Error ? (err as { status?: number }).status : undefined;
+            caught.value = status ? `caught:${status}` : 'caught:unknown';
           }
         }}
       >
diff --git a/packages/docs/src/routes/api/qwik-router-middleware-request-handler/api.json b/packages/docs/src/routes/api/qwik-router-middleware-request-handler/api.json
@@ -356,20 +356,6 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/types.ts",
       "mdFile": "router.internalrequest.md"
     },
-    {
-      "name": "isServerError",
-      "id": "isservererror",
-      "hierarchy": [
-        {
-          "name": "isServerError",
-          "id": "isservererror"
-        }
-      ],
-      "kind": "Function",
-      "content": "Checks whether an error is a `ServerError`<!-- -->. Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.\n\n\n```typescript\nexport declare function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerr\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;E&gt; \\| Error \\| undefined\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nerr is [ServerError](#servererror-variable)<!-- -->&lt;E&gt;",
-      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts",
-      "mdFile": "router.isservererror.md"
-    },
     {
       "name": "mergeHeadersCookies",
       "id": "mergeheaderscookies",
diff --git a/packages/docs/src/routes/api/qwik-router-middleware-request-handler/index.mdx b/packages/docs/src/routes/api/qwik-router-middleware-request-handler/index.mdx
@@ -872,48 +872,6 @@ export type InternalRequest = false | "loader" | "action";
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/types.ts)
 
-<h2 id="isservererror">isServerError</h2>
-
-Checks whether an error is a `ServerError`. Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.
-
-```typescript
-export declare function isServerError<E>(
-  err: ServerError<E> | Error | undefined,
-): err is ServerError<E>;
-```
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-err
-
-</td><td>
-
-[ServerError](#servererror-variable)&lt;E&gt; \| Error \| undefined
-
-</td><td>
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-err is [ServerError](#servererror-variable)&lt;E&gt;
-
-[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts)
-
 <h2 id="mergeheaderscookies">mergeHeadersCookies</h2>
 
 ```typescript
diff --git a/packages/docs/src/routes/api/qwik-router/api.json b/packages/docs/src/routes/api/qwik-router/api.json
@@ -408,20 +408,6 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.httperrorprops.md"
     },
-    {
-      "name": "isServerError",
-      "id": "isservererror",
-      "hierarchy": [
-        {
-          "name": "isServerError",
-          "id": "isservererror"
-        }
-      ],
-      "kind": "Function",
-      "content": "Checks whether an error is a `ServerError`<!-- -->. Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.\n\n\n```typescript\nexport declare function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerr\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;E&gt; \\| Error \\| undefined\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nerr is [ServerError](#servererror-variable)<!-- -->&lt;E&gt;",
-      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts",
-      "mdFile": "router.isservererror.md"
-    },
     {
       "name": "JSONObject",
       "id": "jsonobject",
diff --git a/packages/docs/src/routes/api/qwik-router/index.mdx b/packages/docs/src/routes/api/qwik-router/index.mdx
@@ -1130,48 +1130,6 @@ export type HttpStatus = {
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts)
 
-<h2 id="isservererror">isServerError</h2>
-
-Checks whether an error is a `ServerError`. Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.
-
-```typescript
-export declare function isServerError<E>(
-  err: ServerError<E> | Error | undefined,
-): err is ServerError<E>;
-```
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-err
-
-</td><td>
-
-[ServerError](#servererror-variable)&lt;E&gt; \| Error \| undefined
-
-</td><td>
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-err is [ServerError](#servererror-variable)&lt;E&gt;
-
-[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts)
-
 <h2 id="jsonobject">JSONObject</h2>
 
 ```typescript
diff --git a/packages/docs/src/routes/docs/(qwikrouter)/route-loader/index.mdx b/packages/docs/src/routes/docs/(qwikrouter)/route-loader/index.mdx
@@ -119,7 +119,7 @@ if (product.error) {
 }
 ```
 
-<Note>When an error reaches you as `unknown` (a `catch` block around `submit()` or `resolveValue()`), narrow it with the `isServerError()` guard exported from `@qwik.dev/router`. Prefer it over `instanceof ServerError`, which is `false` on the client after deserialization.</Note>
+<Note>When an error reaches you as `unknown` (a `catch` block around `resolveValue()`), check it structurally — `err instanceof Error && typeof err.status === 'number'` — since `instanceof ServerError` is `false` on the client after deserialization.</Note>
 
 ### Aborting to the error page
 
diff --git a/packages/docs/src/routes/docs/upgrade/index.mdx b/packages/docs/src/routes/docs/upgrade/index.mdx
@@ -269,7 +269,7 @@ What moved is the consumer side. In v1, `fail()` results landed on `action.value
 
 - The `StrictUnion` success/failure value unions are gone — no more `action.value?.failed` narrowing. `FailReturn<T>` still exists but is symbol-branded; it no longer has a `failed: true` property and never appears in `.value`'s type. `fail()` payloads are type-inferred into `.error` instead.
 - Loaders that used `throw error(status, data)` to render error pages **keep that behavior** — thrown `error()`s abort to the error page and never land on `.error`.
-- On loaders, `.error` can also hold a plain `Error` on the client (the loader's fetch itself failed). Its `status` and payload fields are typed optional across the union, so a plain property check discriminates (`if (loader.error?.status)`). Reading `loader.value` while the signal is in error state throws — check `.error` first. In `catch` blocks (around `submit()` or `resolveValue()`), narrow with the `isServerError()` guard (`instanceof ServerError` is `false` on the client after deserialization).
+- On loaders, `.error` can also hold a plain `Error` on the client (the loader's fetch itself failed). Its `status` and payload fields are typed optional across the union, so a plain property check discriminates (`if (loader.error?.status)`). Reading `loader.value` while the signal is in error state throws — check `.error` first. In `catch` blocks (around `submit()` or `resolveValue()`), check errors structurally (`typeof err.status === 'number'`) — `instanceof ServerError` is `false` on the client after deserialization.
 
 ### Serialization
 
diff --git a/packages/qwik-router/src/middleware/request-handler/fail.ts b/packages/qwik-router/src/middleware/request-handler/fail.ts
@@ -65,23 +65,6 @@ export function getFailMeta(value: Failed): FailMeta {
   return value[FailBrand];
 }
 
-/**
- * Checks whether an error is a `ServerError`. Structural rather than `instanceof` so it also
- * matches ServerErrors that crossed a serialization boundary.
- *
- * @public
- */
-export function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;
-/** @public */
-export function isServerError<T = unknown>(err: unknown): err is ServerError<T>;
-export function isServerError(err: unknown): boolean {
-  return (
-    err instanceof Error &&
-    typeof (err as { status?: unknown }).status === 'number' &&
-    'data' in err
-  );
-}
-
 export function failToServerError(value: FailReturn<Record<string, any>>): ServerError {
   const { ...payload } = value;
   return new ServerError(getFailMeta(value).status, payload);
diff --git a/packages/qwik-router/src/middleware/request-handler/index.ts b/packages/qwik-router/src/middleware/request-handler/index.ts
@@ -8,7 +8,7 @@ export { isStaticPath } from './static-paths';
 export { mergeHeadersCookies } from './cookie';
 
 export { ServerError } from './server-error';
-export { FailBrand, isServerError } from './fail';
+export { FailBrand } from './fail';
 export type { Failed, FailMeta, FailReturn, ExcludeFail, FailPayload } from './fail';
 export { AbortMessage, RedirectMessage } from './redirect-handler';
 export { RewriteMessage } from './rewrite-handler';
diff --git a/packages/qwik-router/src/middleware/request-handler/middleware.request-handler.api.md b/packages/qwik-router/src/middleware/request-handler/middleware.request-handler.api.md
@@ -123,12 +123,6 @@ export function getNotFound(prefix: string): string;
 // @public
 export type InternalRequest = false | 'loader' | 'action';
 
-// @public
-export function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;
-
-// @public (undocumented)
-export function isServerError<T = unknown>(err: unknown): err is ServerError<T>;
-
 // Warning: (ae-internal-missing-underscore) The name "isStaticPath" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
diff --git a/packages/qwik-router/src/middleware/request-handler/resolve-request-handlers.unit.ts b/packages/qwik-router/src/middleware/request-handler/resolve-request-handlers.unit.ts
@@ -6,7 +6,6 @@ import {
   resolveRequestHandlers,
 } from './resolve-request-handlers';
 import { RequestEvHttpStatusMessage, RequestEvSharedActionId } from './request-event-core';
-import { isServerError } from './fail';
 import { createRequestEvent } from './request-event';
 import { RedirectMessage } from './redirect-handler';
 import { isContentType } from './request-utils';
@@ -429,8 +428,9 @@ describe('resolve-request-handler', () => {
           await ev.resolveValue(fastFail);
           return { reached: true };
         } catch (err) {
+          const caught = err instanceof Error && typeof (err as any).status === 'number';
           return {
-            caught: isServerError(err),
+            caught,
             status: (err as any).status,
             data: (err as any).data,
           };
diff --git a/packages/qwik-router/src/runtime/src/fail.unit.ts b/packages/qwik-router/src/runtime/src/fail.unit.ts
@@ -5,7 +5,6 @@ import {
   failReturn,
   getFailMeta,
   isFailReturn,
-  isServerError,
 } from '../../middleware/request-handler/fail';
 import type { ServerError } from '../../middleware/request-handler/server-error';
 import { routeLoader$ } from './route-loaders';
@@ -150,9 +149,6 @@ describe('fail() types — loaders', () => {
       expectTypeOf(err.status).toEqualTypeOf<number>();
       expectTypeOf(err.notFound).toEqualTypeOf<boolean>();
     }
-    if (isServerError(loader.error)) {
-      expectTypeOf(loader.error.notFound).toEqualTypeOf<boolean>();
-    }
   });
 
   test('validator$ failure type (FailOfRest) unions with body fail payloads', () => () => {
@@ -172,12 +168,10 @@ describe('fail() types — loaders', () => {
     );
     const loader = useLoader();
     expectTypeOf(loader.value).toEqualTypeOf<{ product: string }>();
-    if (isServerError(loader.error)) {
-      expectTypeOf(loader.error.data).toMatchTypeOf<
-        { notFound: boolean } | { forbidden: boolean }
-      >();
-      expectTypeOf(loader.error.forbidden).toEqualTypeOf<boolean | undefined>();
-    }
+    expectTypeOf(loader.error?.data).toMatchTypeOf<
+      { notFound: boolean } | { forbidden: boolean } | undefined
+    >();
+    expectTypeOf(loader.error?.forbidden).toEqualTypeOf<boolean | undefined>();
   });
 });
 
diff --git a/packages/qwik-router/src/runtime/src/form-component.tsx b/packages/qwik-router/src/runtime/src/form-component.tsx
@@ -65,8 +65,7 @@ export const Form = <O, I>(
             !reloadDocument
               ? $((evt: SubmitEvent) => {
                   if (!action.submitted) {
-                    // Swallow our own rejection — submitcompleted is the form's abort channel.
-                    return action.submit(evt).catch(() => {});
+                    return action.submit(evt);
                   }
                 })
               : undefined,
@@ -87,7 +86,7 @@ export const Form = <O, I>(
           // Since v2, this fires before the action is executed so it can be prevented
           onSubmit$,
           // action.submit "submitcompleted" event for onSubmitCompleted$ events
-          !reloadDocument ? $((evt: SubmitEvent) => action.submit(evt).catch(() => {})) : undefined,
+          !reloadDocument ? action.submit : undefined,
         ],
         method: 'post',
         ['data-spa-reset']: spaReset ? 'true' : undefined,
diff --git a/packages/qwik-router/src/runtime/src/index.ts b/packages/qwik-router/src/runtime/src/index.ts
@@ -90,7 +90,6 @@ export {
   zodQrl,
 } from './server-functions';
 export { routeLoader$, routeLoaderQrl } from './route-loaders';
-export { isServerError } from '../../middleware/request-handler/fail';
 export { ServerError } from '../../middleware/request-handler/server-error';
 export { ServiceWorkerRegister } from './sw-component';
 export {
diff --git a/packages/qwik-router/src/runtime/src/qwik-router.runtime.api.md b/packages/qwik-router/src/runtime/src/qwik-router.runtime.api.md
@@ -259,12 +259,6 @@ export type HttpErrorProps = {
 
 export { InternalRequest }
 
-// @public
-export function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;
-
-// @public (undocumented)
-export function isServerError<T = unknown>(err: unknown): err is ServerError<T>;
-
 // @public (undocumented)
 export type JSONObject = {
     [x: string]: JSONValue;
diff --git a/packages/qwik-router/src/runtime/src/route-loaders.unit.ts b/packages/qwik-router/src/runtime/src/route-loaders.unit.ts
@@ -1,6 +1,6 @@
 import { describe, expect, expectTypeOf, it, test, vi } from 'vitest';
 import { _UNINITIALIZED, type SerializationStrategy } from '@qwik.dev/core/internal';
-import { failReturn, isServerError } from '../../middleware/request-handler/fail';
+import { failReturn } from '../../middleware/request-handler/fail';
 import { ServerError } from '../../middleware/request-handler/server-error';
 import { RedirectMessage } from '../../middleware/request-handler/redirect-handler';
 import {
@@ -227,10 +227,8 @@ describe('types', () => {
     });
     const loader = useObj();
     expectTypeOf(loader.value).toEqualTypeOf<{ result: string }>();
-    if (isServerError(loader.error)) {
-      expectTypeOf(loader.error.status).toEqualTypeOf<number>();
-      expectTypeOf(loader.error.data).toEqualTypeOf<{ message: string }>();
-    }
+    expectTypeOf(loader.error?.status).toEqualTypeOf<number | undefined>();
+    expectTypeOf(loader.error?.data).toMatchTypeOf<{ message: string } | undefined>();
   });
 
   test('thrown error() aborts the request and never lands on loader.error', () => () => {
diff --git a/packages/qwik-router/src/runtime/src/server-functions.ts b/packages/qwik-router/src/runtime/src/server-functions.ts
@@ -134,6 +134,7 @@ Action.run() can only be called on the browser, for example when a user clicks a
                 detail: detail,
               })
             );
+            return { status, value: undefined, error: undefined };
           }
           throw aborted;
         }
diff --git a/packages/qwik-router/src/runtime/src/types.ts b/packages/qwik-router/src/runtime/src/types.ts
@@ -987,9 +987,10 @@ export type ActionStore<RETURN, INPUT, OPTIONAL extends boolean = true, ERROR =
    * `<form>`, a 'click' handle can call the `run()` method of the action in order to execute the
    * action in the server.
    *
-   * Resolves with `{ status, value, error }`; rejects when the submission aborts (a thrown
-   * `error()` or an unexpected server error) — narrow with `isServerError()`. `<Form>` handles the
-   * rejection internally and surfaces aborts via the `submitcompleted` event's `detail.aborted`.
+   * Resolves with `{ status, value, error }` — expected failures (a returned `fail()` or a failed
+   * validator) come back on `error`. A programmatic invocation rejects when the submission aborts
+   * (a thrown `error()` or an unexpected server error); `<Form>` submissions surface aborts via the
+   * `submitcompleted` event's `detail.aborted` instead.
    */
   readonly submit: QRL<
     OPTIONAL extends true

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@qwik.dev/router': patch
 +---
++
 +`ServerError` no longer flattens reserved payload keys (`message`, `status`, `data`, ...) onto the error — `error.message` is always a string and payloads can't clobber `Error` internals.
Original file line number	Diff line number	Diff line change
`@@ -119,7 +119,7 @@ if (product.error) {`
`119`	`119`	`}`
`120`	`120`	```
`121`	`121`
`122`		-<Note>When an error reaches you as `unknown` (a `catch` block around `submit()` or `resolveValue()`), narrow it with the `isServerError()` guard exported from `@qwik.dev/router`. Prefer it over `instanceof ServerError`, which is `false` on the client after deserialization.</Note>
	`122`	+<Note>When an error reaches you as `unknown` (a `catch` block around `resolveValue()`), check it structurally — `err instanceof Error && typeof err.status === 'number'` — since `instanceof ServerError` is `false` on the client after deserialization.</Note>
`123`	`123`
`124`	`124`	`### Aborting to the error page`
`125`	`125`