Invalidation fails for query keys with null when a disabled query uses undefined in the key

[mctep]

Describe the bug

When a disabled query is registered with undefined in its queryKey, invalidation stops working for other queries that have null in the same key position.

This behavior is unexpected, since null and undefined should not be treated as equivalent or conflicting in this context.

Your minimal, reproducible example

https://codesandbox.io/p/sandbox/s3fw8s

Steps to reproduce

1. Define a disabled query with undefined in the key:

useQuery({
  queryKey: ['query', undefined],
  enabled: false,
});

2. Define an enabled query with null in the key:

useQuery({
  queryKey: ['query', null],
  queryFn: () => Math.random()
});

3. Invalidate the second query:

useQueryClient().invalidateQueries({ queryKey: ['query', null] })

Expected behavior

The second query (with null in its key) should be invalidated and refetched.

Actual behavior
Nothing happens — the query is not invalidated or refetched.

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS: macOS Sequoia Version 15.5 (24F74)
• Browser: Chrome
• Version: 138.0.7204.101 (Official Build) (arm64)

Tanstack Query adapter

react-query

TanStack Query version

5.83.0

TypeScript version

4.4.4

Additional context

I suspected the issue might be related to how react-query serializes keys internally (e.g., via JSON.stringify). However, even if:

• undefined is converted to null, both keys would be equivalent, and invalidation should still work (case 2 in CodeSandbox example).
• undefined is omitted or transformed into a different form, keys should remain distinct and not interfere with each other (case 3 in CodeSandbox example).

[TkDodo]

looked into this, and yeah this won’t work. If you have two different keys that serialize to the same value, the queryKey that gets stored on the query is the one from the first invocation. We don’t update it because the key is the identifier and can never change, so this is a case we don’t cover because different keys shouldn’t serialize to the same value.

Query matching is done on the queryKey itself, not the queryHash unless you use the exact filter. I guess what we could do is run every piece of the queryKey through the hashing function while matching. But I’m really sure if that’s worth it

[mctep]

Hi! I’d like to provide a more realistic example, as I believe this is a fairly common pattern in real-world applications.

Imagine we have an article page. The article content can be committed (saved versions) and viewed at any point in its history. Editors can also modify the content.

• Readers can view committed versions of the article.
• Editors can view and edit the latest uncommitted version.
• The backend serves the article based on a version ID:
  • A string version ID represents a committed version.
  • null represents the editable working version.

When the page is loaded, we first need to fetch the version the user is allowed to access. Only after that do we fetch the article content.

• If the user is an editor, the version is null.
• If the user is a reader, the version is a string.
• Before we know the version, we disable the article query to avoid calling it prematurely.

This setup works fine when the editor opens the page (i.e. version is null from the start). However, once the editor updates the content and we want to re-fetch the latest state from the backend, invalidation stops working — because the query was registered earlier with undefined in the key (when version hadn’t been loaded yet).

CodeSandbox Reproduction

This pattern isn’t contrived — it can happen anytime a query depends on another query’s result which could be null. If undefined ends up in the key even once, invalidation can silently break later on.

The only workaround I’ve found is to replace undefined with a placeholder string inside the query key. This prevents the issue by ensuring the key never contains undefined.

function fixRQUndefinedKey(key: unknown) {
  return key === undefined ? 'undefined' : key;
}

const articleQuery = useQuery({
  enabled: version !== undefined,
  queryKey: ["fetchArticle", fixRQUndefinedKey(version)],
  queryFn: () => {
    assert(version !== undefined, "Version must be resolved before fetching");
    return fetchArticle(version);
  },
});

[TkDodo]

If the user is an editor, the version is null.
If the user is a reader, the version is a string.

okay then why is it undefined initially? And it doesn’t sound like you would be happy if we’d treat undefined and null as equal (because they serialize to the same thing) because that would mean undefined means the user is an editor, too. And if that’s the case, you could also always fall-back to version ?? null instead of coming up with a placeholder 🤔

[mctep]

The version is initially undefined because the client doesn't yet know whether the user has editing permissions or what specific version ID to use to fetch the article content. That information is loaded asynchronously on page load.

You're right, falling back to null via version ?? null is definitely a cleaner solution here.

Just a thought. Maybe queries with enabled: false could avoid being cached or registered at all until they become enabled? That way, intermediate states like undefined wouldn't interfere with future matching or invalidation logic.

In any case, thank you so much for your time and help! I'm happy to close the issue.