feat(query-core): pass failureCount to QueryCache onError callback

[n-satoshi061]

Summary

Closes #10713.

Adds a third failureCount parameter to QueryCacheConfig.onError, indicating how many retry attempts occurred before the final failure:

• 0 — the initial attempt failed (no retries happened)
• n — n retries were exhausted before giving up

This makes it easy to implement differentiated error handling without having to derive the count from query.state.fetchFailureCount:

new QueryCache({
  onError: (error, query, failureCount) => {
    if (failureCount === 0) {
      toast.error('Request failed')
    } else {
      toast.error(`Request failed after ${failureCount} retries`)
    }
  },
})

The value is consistent with the failureCount convention already used in ShouldRetryFunction and RetryDelayFunction.

Test plan

• Updated existing onError test to assert failureCount = 0 when no retries occur
• Added new test asserting failureCount equals the configured retry count when retries are exhausted
• All @tanstack/query-core tests pass (527 tests)
• All @tanstack/react-query tests pass (542 tests)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features
  • Error callbacks now receive a failureCount parameter indicating the number of retry attempts before the final error occurred. A value of 0 means no retries were attempted. This enables conditional error handling logic based on retry behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a829c37f-5f88-4ad7-ac3b-27c5f6ce6546

📥 Commits

Reviewing files that changed from the base of the PR and between ba6e7be and 7faa498.

📒 Files selected for processing (4)

• .changeset/feat-query-cache-on-error-failure-count.md
• packages/query-core/src/__tests__/queryCache.test.tsx
• packages/query-core/src/query.ts
• packages/query-core/src/queryCache.ts

---

📝 Walkthrough

Walkthrough

The PR extends the QueryCache onError callback signature to receive a failureCount parameter indicating how many retry attempts preceded the final error. Query fetch logic tracks retries and forwards the count when invoking the error callback. Tests validate the new behavior, and a changeset documents the feature.

Changes

Query onError Callback with Retry Count

Layer / File(s)	Summary
onError callback signature update packages/query-core/src/queryCache.ts	QueryCacheConfig.onError callback type is extended with failureCount: number as a third parameter, allowing consumers to branch error handling based on retry count.
Query retry tracking and callback invocation packages/query-core/src/query.ts	Query.fetch initializes retryCount to zero, updates it when retry failures occur in the retryer's onFail callback, and passes it as an additional argument to the cache-level onError callback.
Test validation and feature documentation packages/query-core/src/__tests__/queryCache.test.tsx, .changeset/feat-query-cache-on-error-failure-count.md	Existing error test assertions are updated to expect failureCount in onError calls; a new test validates that onError receives the final retry count after retries are exhausted; changeset documents the signature change with examples of conditional error handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A whisker-tuned callback now knows when retries fail,
Each attempt tallied true, the count won't derail.
Error handlers branch on retry's final say,
While tests guard the logic—hop on, all's okay! 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a failureCount parameter to QueryCache onError callback.
Description check	✅ Passed	The description covers the changes (failureCount parameter), motivation (differentiated error handling), test plan, and includes a changeset reference.
Linked Issues check	✅ Passed	The PR successfully implements the feature requested in #10713 by passing failureCount to the onError callback, enabling differentiated error handling based on retry attempts.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing the failureCount parameter for the onError callback and updating tests to validate the feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}