useSuspenseQuery's `status` can be `"error"`

[Gpx]

Describe the bug

According to useSuspenseQuery's docs:

status is always success

But the type for status is "error" | "success". It should be "success" only.

Your minimal, reproducible example

https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ4A0KGAymmOgHYba55wC+cAZlBCHAEQACMAhtX4BjANYB6KOj5CYAWgCOOfJwDcAKDVCIgxHFT8YaRnAC8xLErwAKJIroBpdHgBccANoBdInfwAxSq5WAJSmAHyITAxB6mJicPEJAHoA-BpaOkj6fIaoxmZo6GSoFNQWdDZwPniOLu5elZb+gSEm4QiR0WqxCUmpQA

Steps to reproduce

1. Invoke useSuspenseQuery
2. Verify the type of the status property

Expected behavior

As a user, I expected the type of status for useSuspenseQuery to be "success", but I am seeing "error" | "success"

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS: macOS
• Browser: Arc (Chromium)
• Version: 1.89.0 (135.0.7049.42)

Tanstack Query adapter

react-query

TanStack Query version

v5.72.2

TypeScript version

v5.8.3

Additional context

No response

[TkDodo]

The status can be error because we don’t throw all errors to the errorBoundary - only those where we have no data to display.

So if you have a successful fetch that returns myData, and then later get a background refetch error that yields myError, you query will be in the following state:

status: 'error',
data: myData,
error: myError

so that you can decide if you want to keep displaying (stale) data from a previous fetch or not.

[Gpx]

Thanks for the explanation. Should the docs be updated to clarify this? Right now they say that "status is always success" but this is not true since it can sometimes be error.

[TkDodo]

oh yeah please do that 👍