Skip to content

fix: abort timed-out requests with TimeoutError #4045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
manwithacat wants to merge 1 commit into
base: four-dev
Choose a base branch
from
+22 −1
Open

fix: abort timed-out requests with TimeoutError #4045

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/htmx.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -671,7 +671,9 @@ var htmx = (() => {
? this.parseInterval(ctx.request.timeout)
: this.config.defaultTimeout;
if (timeout) {
ctx.requestTimeout = setTimeout(() => ctx.request?.abort?.(), timeout);
ctx.requestTimeout = setTimeout(() => {
ctx.request?.abort?.(new DOMException("Request timed out", "TimeoutError"));

@salomvary salomvary Sep 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to name the DOMException something htmx specific so that it is not going to get confused with a "native" TimeoutError? https://developer.mozilla.org/en-US/docs/Web/API/DOMException#timeouterror

Something like signal.reason.name === 'htmx.TimeoutError'?

@manwithacat manwithacat Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. I used the standard TimeoutError name on purpose so this matches AbortSignal.timeout() and the usual reason.name === 'TimeoutError' check.

The distinction between an htmx timeout and a “native” timeout is empty: they are the same kind of event. The request ran out of time. Colliding with the platform TimeoutError is the goal, not something to avoid.

A custom htmx.TimeoutError would only help if we needed to tell htmx’s timer apart from another timeout on the same signal, which isn’t the #4021 case.

@salomvary salomvary Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A custom htmx.TimeoutError would only help if we needed to tell htmx’s timer apart from another timeout on the same signal, which isn’t the #4021 case.

I'm not sure that's true. My use case, which I think is the same problem as outlined in #4021 is the following: as a lazy solution to handling all sorts of network errors and unexpected server responses, we show a generic "something went wrong" error notification in the UI whenever an htmx:error event is triggered.

And the problem we are seeing with htmx 4 is the very specific hx-sync="this:replace" case, where htmx itself aborts "obsolete" pending requests, in which case we don't want to show an error notification, because this is "business as usual".

But I might as well be misreading what/how this fix achieves :)

@manwithacat manwithacat Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the patch:

  • an hx-sync="this:replace" cancellation still has signal.reason.name === "AbortError"
  • an actual request timeout has signal.reason.name === "TimeoutError"

So in your generic htmx:error handler you can treat AbortError as the expected “obsolete request was replaced” case and ignore it, while still treating TimeoutError as a genuine failure.

The reason I used the standard TimeoutError name rather than htmx.TimeoutError is that there doesn’t seem to be any additional htmx-specific distinction to encode here. A timeout produced by htmx’s timer has the same semantics as AbortSignal.timeout(): the operation exceeded its allotted time.

I do think your separate point about this being a behavioural change from htmx 2 is worth documenting. If htmx:error now includes expected cancellations such as hx-sync replacement, applications with a generic error handler need to know that they should discriminate on the abort reason.

@MichaelWest22 MichaelWest22 Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah in the ideal world we would actually use AbortSignal.timeout and not use our own custom setTimeout. But for this to work we need to wrap it in AbortSignal.any() so we can keep the manual abort as an option as well and these two features are too newly released to be used yet in htmx without expensive fallback code.

to keep the code change minimal we should just be returning a text error reason directly like:

ctx.requestTimeout = setTimeout(() => ctx.request?.abort?.('timeout'), timeout);

or maybe 'RequestTimeout'
This makes it clear it is just a custom timeout being reported by htmx and not trying to fake a standard abort signal error.

but aborts via hx-sync or manual htmx:abort events are not errors but are thrown as errors to be caught by the abort controller we use. so we should probably also do:

            } catch (error) {
                ctx.status = "error: " + error;
                if (error?.name !== 'AbortError') this.__trigger(elt, "htmx:error", {ctx, error})
            } finally {

to swallow this expected thrown error ideally

}, timeout);
}
}

Expand Down
17 changes: 17 additions & 0 deletions test/tests/unit/__issueRequest.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,23 @@ describe('__issueRequest unit tests', function() {
await htmx.__issueRequest(ctx)
assert.isTrue(errorFired)
assert.isTrue(ctx.request.signal.aborted)
assert.equal(ctx.request.signal.reason?.name, 'TimeoutError')
})

it('timeout abort reason is distinguishable from hx-sync replace', async function () {
let div = createProcessedHTML('<div hx-get="/test" hx-swap="none" hx-sync="this:replace"></div>')
let ctx = htmx.__createRequestContext(div, new Event('click'))
ctx.fetch = (url, opts) => new Promise((_, reject) => {
opts.signal.addEventListener('abort', () => {
reject(opts.signal.reason || new DOMException('The operation was aborted', 'AbortError'))
})
})
let p = htmx.__issueRequest(ctx)
await new Promise(r => setTimeout(r, 10))
ctx.request.abort()
await p
assert.isTrue(ctx.request.signal.aborted)
assert.notEqual(ctx.request.signal.reason?.name, 'TimeoutError')
})

it('htmx:abort event aborts in-flight request', async function () {
Expand Down
2 changes: 2 additions & 0 deletions www/src/content/reference/03-events/11-htmx-error.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,6 @@ htmx.on('htmx:error', (evt) => {
});
```

Timeouts and intentional aborts (`hx-sync` replace/abort, `htmx:abort`) both surface as a failed `fetch()`. Distinguish them with `ctx.request.signal.reason`: a timeout uses `TimeoutError` (`"Request timed out"`); a user or sync abort remains `AbortError`.

Use this for centralized error handling and user feedback.
Loading