From 0f510efda8ffba355069bec8c3f72f26be45ad32 Mon Sep 17 00:00:00 2001
From: Slava Razum <razum@qruto.to>
Date: Wed, 4 Nov 2026 14:03:46 +0100
Subject: [PATCH] react: throw the missing ConvexProvider error from
 usePaginatedQuery

---
 src/react/use_paginated_query.ts              |  7 ++++++
 src/react/use_paginated_query2.ts             |  7 ++++++
 .../use_paginated_query_provider.test.tsx     | 24 +++++++++++++++++++
 3 files changed, 38 insertions(+)
 create mode 100644 src/react/use_paginated_query_provider.test.tsx

diff --git a/src/react/use_paginated_query.ts b/src/react/use_paginated_query.ts
index 1122968c..dbf856f0 100644
--- a/src/react/use_paginated_query.ts
+++ b/src/react/use_paginated_query.ts
@@ -268,6 +268,13 @@ export function usePaginatedQueryInternal<
     setState(currState);
   }
   const convexClient = useConvex();
+  if (convexClient === undefined) {
+    throw new Error(
+      "Could not find Convex client! `usePaginatedQuery` must be used in the React component " +
+        "tree under `ConvexProvider`. Did you forget it? " +
+        "See https://docs.convex.dev/quick-start#set-up-convex-in-your-react-app",
+    );
+  }
   const logger = convexClient.logger;
 
   const resultsObject = useQueries(currState.queries);
diff --git a/src/react/use_paginated_query2.ts b/src/react/use_paginated_query2.ts
index 00b30151..756259cf 100644
--- a/src/react/use_paginated_query2.ts
+++ b/src/react/use_paginated_query2.ts
@@ -206,6 +206,13 @@ export function usePaginatedQuery_experimental<
   const argsObject = skip ? {} : queryArgs;
 
   const convexClient = useConvex();
+  if (convexClient === undefined) {
+    throw new Error(
+      "Could not find Convex client! `usePaginatedQuery_experimental` must be used in the React component " +
+        "tree under `ConvexProvider`. Did you forget it? " +
+        "See https://docs.convex.dev/quick-start#set-up-convex-in-your-react-app",
+    );
+  }
   const logger = convexClient.logger;
 
   // The identity of createInitialState changes each time!
diff --git a/src/react/use_paginated_query_provider.test.tsx b/src/react/use_paginated_query_provider.test.tsx
new file mode 100644
index 00000000..b99c07fe
--- /dev/null
+++ b/src/react/use_paginated_query_provider.test.tsx
@@ -0,0 +1,24 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { renderHook } from "@testing-library/react";
+import { expect, test } from "vitest";
+import { makeFunctionReference } from "../server/index.js";
+import { usePaginatedQuery } from "./use_paginated_query.js";
+import { usePaginatedQuery_experimental } from "./use_paginated_query2.js";
+
+const query = makeFunctionReference<"query">("messages:list") as any;
+
+test("usePaginatedQuery names itself when there is no ConvexProvider", () => {
+  expect(() =>
+    renderHook(() => usePaginatedQuery(query, {}, { initialNumItems: 1 })),
+  ).toThrow("Could not find Convex client! `usePaginatedQuery`");
+});
+
+test("usePaginatedQuery_experimental names itself when there is no ConvexProvider", () => {
+  expect(() =>
+    renderHook(() =>
+      usePaginatedQuery_experimental(query, {}, { initialNumItems: 1 }),
+    ),
+  ).toThrow("Could not find Convex client! `usePaginatedQuery_experimental`");
+});