queryCache.findAll() returns wrapped iterable instead of array — breaks standard invalidation APIs

[nicolas-chalet-wmx]

Environment:

• @tanstack/react-query v5.90.2
• React 18.2.0
• Issue occurs in mobile WebViews only, not in Electron

Description:

We're building a library that uses react-query and is consumed by a host application. In certain build configurations (mobile WebViews), we observe unexpected behavior:

const queryCache = useQueryClient().getQueryCache();
const queries = queryCache.findAll();

// Expected: Query[]
// Actual: An array with a single iterable entry that yields Query objects

We suspect this is due to module duplication where our library and the host app resolve to different instances of @tanstack/react-query.

Impact:

Due to this issue, we cannot use the standard react-query APIs for cache management:

// ❌ These do NOT work in our mobile environment:
queryClient.invalidateQueries({ queryKey: ['myKey'] });
queryClient.resetQueries({ queryKey: ['myKey'] });
queryClient.clear();

// ✅ We have to manually iterate and call methods on each Query instance:
const queries = queryCache.findAll();
const normalized = normalizeIterableResult(queries); // our workaround

normalized.forEach((query) => {
  query.invalidate();
  query.reset();
  // or query.fetch() for refetch
});

This forces us to bypass the intended API and work directly with Query instances, which feels brittle and may break with future versions.

Questions:

1. Is this a known behavior when multiple instances coexist?
2. Are there recommended bundler configurations to prevent this?
3. Should react-query detect this scenario and warn developers?
4. Is working directly with Query.invalidate() / Query.reset() / Query.fetch() a supported pattern, or are we relying on internal implementation details?

Workaround:

We currently normalize the result by checking if the first element is iterable:

const normalizeQuery = (maybeNotQuery: Query): Query[] => {
  const isIterator = Symbol.iterator in Object(maybeNotQuery);
  if (isIterator) {
    return [...maybeNotQuery as Iterable<Query>];
  }
  return [maybeNotQuery];
};

const queries = queryCache.findAll().flatMap(normalizeQuery);

[aniruddhaadak80]

@nicolas-chalet-wmx Thanks for the detailed environment notes (especially WebView-only repro).

queryCache.findAll() returning a non-array-like wrapper in one build target strongly suggests an interop/transpilation mismatch (iterator/polyfill/runtime) rather than expected Query API behavior.

Quick isolation steps:

1. log Array.isArray(queryCache.findAll()) and constructor/type in both environments
2. wrap with Array.from(...) before downstream invalidation logic
3. compare transpilation/polyfill targets between Electron and WebView bundles

If this confirms environment-specific iterator behavior, maintainers can likely suggest the most compatible workaround.

References:

• https://tanstack.com/query/latest/docs/framework/react/reference/QueryCache
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from

[travisbreaks]

You have correctly diagnosed the root cause: module duplication. Your library and the host app are resolving to different instances of @tanstack/react-query, which means they have different QueryCache class prototypes. When the host app calls findAll(), it gets back objects from the library's instance whose Array.isArray() check may fail across realm boundaries (this is a known JavaScript behavior when objects cross iframe/WebView/module boundaries).

Why this happens in WebViews specifically

Mobile WebViews often bundle JavaScript differently than desktop browsers or Electron. If your library is pre-bundled (e.g., shipped as a UMD/ESM bundle with react-query inlined), and the host app also has its own react-query dependency, you end up with two separate module instances. Each has its own QueryCache class, its own Query class, and its own internal Map instances.

The fix: deduplicate the module

The goal is to ensure both your library and the host app use the exact same @tanstack/react-query module instance.

Option 1: Mark react-query as a peer dependency (recommended)

In your library's package.json:

{
  "peerDependencies": {
    "@tanstack/react-query": "^5.0.0"
  }
}

Then configure your library's bundler to externalize react-query so it is not inlined into your bundle:

// vite.config.ts (if using Vite for library mode)
export default defineConfig({
  build: {
    lib: { entry: "src/index.ts", formats: ["es"] },
    rollupOptions: {
      external: ["@tanstack/react-query", "react", "react-dom"],
    },
  },
});

Option 2: Bundler alias (host app side)

If you cannot change the library, force the host app's bundler to resolve all react-query imports to a single copy:

// webpack.config.js
resolve: {
  alias: {
    "@tanstack/react-query": require.resolve("@tanstack/react-query"),
  },
}

// vite.config.ts
resolve: {
  dedupe: ["@tanstack/react-query"],
}

Option 3: Stopgap (your current workaround, improved)

If you need an immediate fix while sorting out the bundling:

function normalizeResult<T>(result: T[] | Iterable<T>): T[] {
  return Array.isArray(result) ? result : Array.from(result);
}

This is what you are already doing, and it is fine as a temporary measure. But the real fix is deduplication (Options 1 or 2).

To answer your specific questions

1. Is this known? Yes. Module duplication is a well-documented issue in the React ecosystem, especially for libraries that rely on singleton patterns (React itself, react-query, zustand, jotai). The findAll() returning a wrapped iterable is a symptom of cross-instance prototype mismatch.

2. Is there something the host app can do? Yes: bundler deduplication (Option 2 above). The resolve.dedupe config in Vite or resolve.alias in Webpack forces all imports to resolve to a single physical file.