From 1ef9a10a9dab237c5817e8e945496034edffe460 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Sun, 20 Sep 2026 08:28:16 -0400 Subject: [PATCH 1/2] docs: explain timeout exception factory stacks --- docs/middleware/builtin/timeout.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/middleware/builtin/timeout.md b/docs/middleware/builtin/timeout.md index 9d1c1f891..7d1225fe5 100644 --- a/docs/middleware/builtin/timeout.md +++ b/docs/middleware/builtin/timeout.md @@ -56,6 +56,12 @@ app.get('/api/long-process', async (c) => { }) ``` +::: tip + +Use a factory function when each timeout needs a fresh error stack, such as when reporting exceptions to an observability service. Passing an exception instance reuses that instance and its construction-time stack for every timeout, which can affect stack attribution and error fingerprinting. + +::: + ## Notes - The duration for the timeout can be specified in milliseconds. The middleware will automatically reject the promise and potentially throw an error if the specified duration is exceeded. From 5c897e90052dc8a9fd433aaef97a2c3ba4f91949 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Sun, 20 Sep 2026 09:40:51 -0400 Subject: [PATCH 2/2] docs: add timeout exception factory example --- docs/middleware/builtin/timeout.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/middleware/builtin/timeout.md b/docs/middleware/builtin/timeout.md index 7d1225fe5..8215a632b 100644 --- a/docs/middleware/builtin/timeout.md +++ b/docs/middleware/builtin/timeout.md @@ -56,9 +56,18 @@ app.get('/api/long-process', async (c) => { }) ``` -::: tip +::: tip Fresh error stacks -Use a factory function when each timeout needs a fresh error stack, such as when reporting exceptions to an observability service. Passing an exception instance reuses that instance and its construction-time stack for every timeout, which can affect stack attribution and error fingerprinting. +Use a factory when timeout errors are reported to an observability service: + +```ts +timeout( + 5000, + () => new HTTPException(504, { message: 'Gateway Timeout' }) +) +``` + +Passing an exception instance reuses its construction-time stack for every timeout, which can affect stack attribution and error fingerprinting. :::