From 822372933e6bda58838b1f65bb0445bd60c7fd58 Mon Sep 17 00:00:00 2001
From: Cam Jackson <1930451+camjackson@users.noreply.github.com>
Date: Wed, 31 Dec 2025 14:18:23 +1100
Subject: [PATCH] docs(react-query): undefined vs. null in query-functions.md

---
 docs/framework/react/guides/query-functions.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/framework/react/guides/query-functions.md b/docs/framework/react/guides/query-functions.md
index 4fa621c697..6b4aee921d 100644
--- a/docs/framework/react/guides/query-functions.md
+++ b/docs/framework/react/guides/query-functions.md
@@ -5,6 +5,8 @@ title: Query Functions
 
 A query function can be literally any function that **returns a promise**. The promise that is returned should either **resolve the data** or **throw an error**.
 
+On success, the resolved value may be anything **except `undefined`**. Queries that resolve to `undefined` will be [treated as failed](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-react-query-4#undefined-is-an-illegal-cache-value-for-successful-queries). To store "nothing" as a successful result in the query cache, resolve `null` instead.
+
 All of the following are valid query function configurations:
 
 [//]: # 'Example'
@@ -23,6 +25,13 @@ useQuery({
   queryKey: ['todos', todoId],
   queryFn: ({ queryKey }) => fetchTodoById(queryKey[1]),
 })
+useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: async () => {
+    const allTodosById = await fetchAllTodosById()
+    return allTodosById[todoId] ?? null
+  },
+})
 ```
 
 [//]: # 'Example'