Redux Toolkit 2.15.0, released on 18 November 2026, is one of the more significant RTK Query releases in a while. Each Redux store now gets its own RTK Query runtime, initiate() promises always resolve with their own request’s result, and there are new options such as a function pollingInterval, a startReason on every query, and retainFor for prefetching. Some long-standing bugs were fixed in ways that change edge-case behaviour, so it’s worth reading before you bump the version.

This guide walks through the changes with React examples and gives you an upgrade checklist. Source: the official Redux Toolkit v2.15.0 release notes.

Upgrade

npm install @reduxjs/toolkit@^2.15.0 react-redux

1. A per-store RTK Query runtime

RTK Query’s middleware tracks a lot of state outside the Redux store: subscriber counts, running requests, polling and cache-collection timers, and cache lifecycle promises. Before 2.15, that state lived in closures shared by every store that used the same api object. That was fine for a single browser store, but caused leaks and cross-talk in SSR (one store per request) and tests (one store per test).

Now each store gets its own runtime, created by the API middleware. resetApiState resets only that store’s runtime: it clears subscribers, timers and cache lifecycles, aborts running requests and clears pending tag invalidations, without touching other stores.

For a typical test setup that means this pattern is now reliable:

// test-utils.ts
import { configureStore } from '@reduxjs/toolkit'
import { api } from './api'

export function makeStore() {
  return configureStore({
    reducer: { [api.reducerPath]: api.reducer },
    middleware: (gDM) => gDM().concat(api.middleware),
  })
}

// each test gets a fresh, fully isolated store
beforeEach(() => {
  store = makeStore()
})

Stricter middleware check: an api whose middleware is missing now throws, even if another api with the same reducerPath has its middleware in the store. If you’ve been getting away with a misconfigured store, you’ll find out now.

2. initiate() resolves with its own result

Several issues reported that the promise from initiate() could resolve with undefined or with another request’s data when the cache entry was removed, reset or replaced while the request was running. In 2.15, each initiate() promise resolves with its own request’s result, captured as soon as that request’s fulfilled or rejected action reaches the store.

Behaviour changes that come with it

These ship as bug fixes in 2.x, but code that depended on the old behaviour will notice:

  • Removing a cache entry while its request runs now aborts the request. This covers removeQueryResult, a lazy query’s reset(), cache collection and resetApiState. The promise resolves with isError: true and an AbortError whose message is 'removed' or 'reset', so unwrap() now rejects in this case.
  • queryFulfilled in onQueryStarted rejects in the same case. Unguarded await queryFulfilled becomes an unhandled rejection. Wrap it:
async onQueryStarted(arg, { queryFulfilled, dispatch }) {
  try {
    const { data } = await queryFulfilled
    dispatch(postsLoaded(data))
  } catch {
    // request failed, or the cache entry was removed while it ran
  }
}
  • Invalidating an entry with a running request now waits for that request, then refetches if the entry still has subscribers.
  • A refetch during a running request joins it instead of starting another.
  • onCacheEntryAdded gets getCacheEntryRemovedReason(), which returns 'reset', 'removed' or undefined:
async onCacheEntryAdded(arg, { cacheEntryRemoved, getCacheEntryRemovedReason }) {
  const ws = new WebSocket(`wss://example.com/rooms/${arg}`)
  await cacheEntryRemoved
  if (getCacheEntryRemovedReason() !== 'reset') {
    // e.g. tell the server we left, only on normal removal
  }
  ws.close()
}

3. startReason: know why a query is fetching

Base queries, queryFn, prepareHeaders, onQueryStarted and onCacheEntryAdded now receive a startReason. Possible values are 'initial' | 'refetch' | 'invalidation' | 'poll' | 'focus' | 'reconnect' | 'upsert' | 'hydrate' | 'nextPage' | 'previousPage'. ('hydrate' is reserved and not set yet.)

A practical use from the release notes: after a mutation invalidates data, read from the primary database rather than a replica that might be behind:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

export const api = createApi({
  baseQuery: fetchBaseQuery({
    baseUrl: '/api',
    prepareHeaders: (headers, { startReason }) => {
      if (startReason === 'invalidation') {
        headers.set('x-read-from-primary', 'true')
      }
      return headers
    },
  }),
  endpoints: (build) => ({
    getJob: build.query<Job, string>({ query: (id) => `jobs/${id}` }),
  }),
})

export const { useGetJobQuery } = api

Mutations receive startReason: undefined.

4. Function pollingInterval

“Poll while the job is running, stop when it’s done” used to need extra state or a second hook. Now pollingInterval can be a function of the current cache entry:

function JobStatus({ id }: { id: string }) {
  const { data, isLoading } = useGetJobQuery(id, {
    pollingInterval: ({ data }) => (data?.status === 'running' ? 1000 : 0),
  })

  if (isLoading) return <p>Loading…</p>
  return <p>Status: {data?.status}</p>
}

Returning 0, a negative number or a non-number means “don’t poll”; polling resumes if a later result makes the function return an interval again. An inline function doesn’t dispatch updateSubscriptionOptions on every render.

Related changes to check:

  • A negative numeric pollingInterval now means “no polling” (it used to re-poll immediately in a loop).
  • 'payload.options.pollingInterval' is a new default entry in the serializability check’s ignoredActionPaths. If you pass your own ignoredActionPaths, add it.
  • SubscriptionOptions['pollingInterval'] is now number | ((entry) => number); there’s a new exported PollingInterval type.

5. Prefetch with retainFor and getRunningQuery

Query initiate() accepts retainFor (seconds). After the last subscriber leaves, the entry is kept for Math.max(keepUnusedDataFor, retainFor). And api.endpoints.x.getRunningQuery(arg) returns the running request’s promise (or undefined) without adding a subscription:

// prefetch on hover
dispatch(api.endpoints.getPost.initiate(id, { subscribe: false, retainFor: 60 }))

// later, e.g. in a route loader
const running = dispatch(api.endpoints.getPost.getRunningQuery(id))
if (running) {
  await running
}

6. Nested forks in the listener middleware

ForkedTaskAPI now has getState, dispatch and fork, so forked tasks can start child tasks. Nested forks are cancelled when their parent ends, and autoJoin: true makes the parent wait:

listenerMiddleware.startListening({
  actionCreator: startSync,
  effect: async (action, listenerApi) => {
    listenerApi.fork(async (forkApi) => {
      const { userId } = forkApi.getState().auth
      forkApi.fork(
        async (childApi) => {
          childApi.dispatch(syncStarted(userId))
        },
        { autoJoin: true },
      )
    })
  },
})

7. Smaller things

  • Readable editor hovers. New named types (FetchBaseQueryFn, ApiUtil and others) shrink type hovers. The api.util hover went from 16,102 to 471 characters in the team’s measurements.
  • api.util.getMiddlewareState() and isSubscribed() replace the internal internal_getRTKQSubscriptions action, which is now deprecated and logs a one-time dev warning.
  • Hooks with skip: true on a store without the API middleware no longer throw.

Upgrade checklist

  1. Search for await queryFulfilled without try/catch and wrap it.
  2. Search for .unwrap() on initiate() results where the entry might be removed mid-request.
  3. If you configure ignoredActionPaths, add 'payload.options.pollingInterval'.
  4. If you read pollingInterval as a number in typed code, add a type check.
  5. Make sure every api has its middleware in every store, including test stores.
  6. If you maintain a library that dispatches internal_getRTKQSubscriptions, switch to getMiddlewareState().

Key takeaways

  • RTK 2.15 isolates RTK Query state per store, fixing SSR and test leaks.
  • initiate() promises are now trustworthy, but removed or reset entries make unwrap() and queryFulfilled reject.
  • startReason, function pollingInterval and retainFor remove a lot of hand-written workaround code.
  • This release is a step on the road to RTK 3.0, so it’s a good time to clean up deprecated patterns.