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’sreset(), cache collection andresetApiState. The promise resolves withisError: trueand anAbortErrorwhose message is'removed'or'reset', sounwrap()now rejects in this case. queryFulfilledinonQueryStartedrejects in the same case. Unguardedawait queryFulfilledbecomes 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.
onCacheEntryAddedgetsgetCacheEntryRemovedReason(), which returns'reset','removed'orundefined:
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
pollingIntervalnow means “no polling” (it used to re-poll immediately in a loop). 'payload.options.pollingInterval'is a new default entry in the serializability check’signoredActionPaths. If you pass your ownignoredActionPaths, add it.SubscriptionOptions['pollingInterval']is nownumber | ((entry) => number); there’s a new exportedPollingIntervaltype.
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,ApiUtiland others) shrink type hovers. Theapi.utilhover went from 16,102 to 471 characters in the team’s measurements. api.util.getMiddlewareState()andisSubscribed()replace the internalinternal_getRTKQSubscriptionsaction, which is now deprecated and logs a one-time dev warning.- Hooks with
skip: trueon a store without the API middleware no longer throw.
Upgrade checklist
- Search for
await queryFulfilledwithouttry/catchand wrap it. - Search for
.unwrap()oninitiate()results where the entry might be removed mid-request. - If you configure
ignoredActionPaths, add'payload.options.pollingInterval'. - If you read
pollingIntervalas anumberin typed code, add a type check. - Make sure every
apihas its middleware in every store, including test stores. - If you maintain a library that dispatches
internal_getRTKQSubscriptions, switch togetMiddlewareState().
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 makeunwrap()andqueryFulfilledreject.startReason, functionpollingIntervalandretainForremove 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.
