How to skip query during logout

[silver zephyr]

Hi @north shore. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

When you sign out using Convex Auth, it's common to see "Unauthorized" errors if your queries are still running while the authentication state is transitioning. This happens because queries that require authentication are not automatically skipped during logout, so they attempt to run with an invalid or missing token.

How to skip queries during logout:

You should conditionally skip queries based on the authentication state. Convex provides the useConvexAuth() hook, which exposes isAuthenticated and isLoading. You can use these to prevent queries from running when the user is not authenticated.

Example: Skipping queries until authenticated

import { useConvexAuth, useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

export function MyComponent() {
  const { isAuthenticated } = useConvexAuth();

  const data = useQuery(
    api.organizations.getCurrentRole,
    isAuthenticated ? { /* your args */ } : "skip"
  );

  // ... rest of your component
}

By passing "skip" as the query argument when the user is not authenticated, the query will not execute, and you will avoid unauthorized errors during logout or authentication transitions. This pattern should be applied to all queries that require authentication, especially in components that remain mounted during sign-out transitions.

Why this matters:

• Prevents unauthorized queries and backend errors.
• Optimizes performance by not sending unnecessary requests.
• Avoids race conditions during authentication transitions
  Authentication Best Practices: Ensuring Authentication in Client Components.

For paginated or status queries:
You can create custom hooks to wrap this logic, as shown in the knowledge sources:

import { useConvexAuth, usePaginatedQuery } from "convex/react";

export function useAuthenticatedPaginatedQuery(query, args, options) {
  const { isAuthenticated } = useConvexAuth();
  return usePaginatedQuery(query, isAuthenticated ? args : "skip", options);
}

Paginated Query Hook: Handling Pagination Securely

Summary:
Update your components to skip queries when the user is not authenticated. This will prevent the "Unauthorized" errors you are seeing during logout.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@north shore Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[north shore]

@silver zephyr Which means all useQuery or usePreloadedQuery, I also need to add the skip code?

[silver zephyr]

Let me check the knowledge base for you again. One moment! :books:

---

Yes, you should add the "skip" logic to all useQuery, usePreloadedQuery, and similar hooks that fetch data requiring authentication. This ensures that these queries do not run when the user is not authenticated, preventing unauthorized errors during logout or authentication transitions.

The recommended pattern is to check the authentication state (using useConvexAuth()) and pass "skip" as the query argument if the user is not authenticated. This approach is explicitly documented for useQuery, and the same logic applies to other Convex data-fetching hooks:

const { isAuthenticated } = useConvexAuth();
const data = useQuery(api.someQuery, isAuthenticated ? { ...args } : "skip");

This pattern is also recommended for paginated queries and can be wrapped in custom hooks for convenience. The same principle applies to any Convex query hook that should only run when the user is authenticated Ensuring Authentication in Client Components Paginated Query Hook: Handling Pagination Securely.

If you do not add this logic, your queries may run with an unauthenticated state, resulting in "Unauthorized" errors from the backend.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@north shore Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[north shore]

@silver zephyr Is there a way to skip automatically? or some resuable useQuery hook with the skip function?

I have this:

"use client"

import { makeUseQueryWithStatus } from "convex-helpers/react"
import { useQueries } from "convex-helpers/react/cache/hooks"

export const useQuery = makeUseQueryWithStatus(useQueries)

[silver zephyr]

Let me check the knowledge base for you again. One moment! :books:

---

Yes, you can create a reusable custom hook that automatically skips queries when the user is not authenticated. This pattern is recommended in the Convex community and documentation. The idea is to wrap your query hook and inject the skip logic based on the authentication state from useConvexAuth().

Here’s an example from the knowledge sources, showing how to create such a wrapper for a status-aware query hook:

import { FunctionReference } from 'convex/server';
import {
  OptionalRestArgsOrSkip,
  useConvexAuth,
  useQueryWithStatus,
} from 'convex/react';

/**
 * A wrapper around useQueryWithStatus that automatically checks authentication state.
 * If the user is not authenticated, the query is skipped.
 */
export function useAuthenticatedQueryWithStatus<
  Query extends FunctionReference<'query'>,
>(query: Query, args: OptionalRestArgsOrSkip<Query>[0] | 'skip') {
  const { isAuthenticated } = useConvexAuth();
  return useQueryWithStatus(query, isAuthenticated ? args : 'skip');
}

You can adapt this pattern to your own useQuery implementation. For example, if you are using makeUseQueryWithStatus from convex-helpers, you can create a similar wrapper:

import { useConvexAuth } from "convex/react";
import { makeUseQueryWithStatus } from "convex-helpers/react";
import { useQueries } from "convex-helpers/react/cache/hooks";

const useQueryWithStatus = makeUseQueryWithStatus(useQueries);

export function useAuthenticatedQuery(query, args) {
  const { isAuthenticated } = useConvexAuth();
  return useQueryWithStatus(query, isAuthenticated ? args : "skip");
}

This way, you only need to use useAuthenticatedQuery throughout your app, and it will automatically skip queries when the user is not authenticated, reducing boilerplate and preventing unauthorized errors Authenticated Query Hooks: Simplifying Authentication Logic.

If you need similar logic for paginated queries, you can use the same approach as shown in the sources.

In summary:
Yes, you can and should create a reusable hook to automatically handle skipping queries based on authentication state, as shown above.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@north shore Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[north shore]

@silver zephyr I still getting the same error even used the skip

[silver zephyr]

Let me check the knowledge base for you again. One moment! :books:

---

If you are still getting "Unauthorized" errors from Convex queries even after using the "skip" argument, there are a few possible reasons based on the knowledge sources:

1. Queries may still be running during the auth transition:
   Even with "skip", if a query is already in-flight or if the component is not unmounted quickly enough during logout, you may still see unauthorized errors. This is a known issue, especially with integrations like TanStack Query or when using Suspense, where queries can remain active for a short period after logout. Convex staff have acknowledged that queries can be "refreshed" or retried with an unauthenticated state during sign-out, leading to these errors. This is a client ordering/race condition that is being worked on, but not fully solved yet Discord: Roast of the convex client and authentication.

2. Convex queries are not automatically unsubscribed on logout:
   When you log out, queries may still be subscribed for a short time, and the Convex client will attempt to refresh them with the new (unauthenticated) state, causing backend errors. This is especially true with TanStack Query integration, as mentioned by Convex staff Discord: Roast of the convex client and authentication.

3. Throwing errors in backend auth checks:
   If your Convex backend throws an error when unauthenticated, you will see these errors in your logs whenever a query is attempted without a valid user. Some teams choose to return null or a safe value instead of throwing, to avoid noisy logs during expected transitions like logout Discord: How to correctly signOut with clerk.

What you can do:

• Double-check that all your queries use the "skip" logic and that no queries are running outside of an authenticated context.
• Consider returning null or a safe value from your backend queries when unauthenticated, instead of throwing, to reduce log noise.
• Be aware that, as of now, there is no fully automatic way to guarantee that no queries will run during the logout transition—this is a known limitation and an area of ongoing improvement in Convex.

Summary:
Even with "skip", some unauthorized errors may still occur during logout due to how query subscriptions and auth transitions are handled in Convex. This is a known issue, and while using "skip" is best practice, you may need to handle or suppress these errors in your backend for now. If this is a major problem for your app, you may want to follow updates from the Convex team as they work on improving this behavior Discord: Roast of the convex client and authentication.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: