fix(query-core): make retry failureCount 1-based

[KyungHwanKim-devs]

🎯 Changes

• Fix retry callback failureCount to start at 1 on the first failure (query-core)
• Add a regression test covering retry callback counts
• Document the 1-based failureCount in retry docs

Fixes #10017

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr. (Ran npx nx run @tanstack/query-core:test:lib)

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes

  • Fixed retry callback behavior so failureCount starts at 1 on the first failure.

• Documentation

  • Clarified retry option docs across frameworks to note failureCount is 1-based for custom retry functions.

• Tests

  • Added test coverage verifying the 1-based failureCount behavior in retry callbacks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: b3e528d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@tanstack/query-core	Patch
@tanstack/angular-query-experimental	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-persist-client-core	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query	Patch
@tanstack/solid-query	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query	Patch
@tanstack/angular-query-persist-client	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/vue-query-devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR changes retry behavior to pass a 1-based failureCount (starts at 1 on first failure) to retry callbacks, adds a test asserting this behavior, and updates multiple docs and a changelog entry to reflect the change.

Changes

Cohort / File(s)	Summary
Changelog .changeset/bright-rabbits-jump.md	Adds a new changeset entry documenting the patch that makes retry callback failureCount 1-based.
Documentation docs/framework/react/guides/query-retries.md, docs/framework/react/reference/useQuery.md, docs/framework/react/reference/useMutation.md, docs/framework/solid/reference/useQuery.md	Clarifies that when retry is a function, failureCount starts at 1 on the first failed attempt.
Core Logic packages/query-core/src/retryer.ts	Calls retry callback with failureCount + 1 instead of failureCount (adjusts the value passed into the retry function).
Tests packages/query-core/src/__tests__/query.test.tsx	Adds a test that verifies retry callbacks receive 1-based failureCount values (records [1, 2] across attempts).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hop through code with counting fun,
Now retries start their tally at one.
Docs and tests all sing along,
A tiny fix, but crisp and strong.
✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(query-core): make retry failureCount 1-based' directly and clearly describes the main change: converting failureCount from 0-based to 1-based in retry callbacks.
Description check	✅ Passed	The description follows the template structure with filled Changes, Checklist, and Release Impact sections. It clearly outlines the three main modifications and references the linked issue.
Linked Issues check	✅ Passed	The PR successfully addresses issue #10017 by changing failureCount from 0-based to 1-based, adding test coverage, and updating documentation across multiple framework docs.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the issue requirements: modifying retry logic, adding regression test, and updating documentation consistently across frameworks.

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

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3ab13a7 and b3e528d.

📒 Files selected for processing (1)

• docs/framework/react/guides/query-retries.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/framework/react/guides/query-retries.md

---

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/framework/react/guides/query-retries.md (1)

10-13: Documentation content is accurate; consider varying sentence structure for readability.

The new explanation of the function-based retry behavior is clear and correct. However, four successive list items beginning with "Setting" creates repetitive phrasing that could be improved. Consider rewording one or more items to vary the sentence structure while preserving the clarity of each option.

♻️ Suggested refactor for improved readability

- Setting `retry = false` will disable retries.
- Setting `retry = 6` will retry failing requests 6 times before showing the final error thrown by the function.
- Setting `retry = true` will infinitely retry failing requests.
- Setting `retry = (failureCount, error) => ...` allows for custom logic based on why the request failed. The `failureCount` starts at `1` for the first failure.
+ - `retry = false` disables retries.
+ - `retry = 6` will retry failing requests 6 times before showing the final error thrown by the function.
+ - `retry = true` will infinitely retry failing requests.
+ - `retry = (failureCount, error) => ...` allows for custom logic based on why the request failed. The `failureCount` starts at `1` for the first failure.

Alternatively, vary the opening phrases further (e.g., "Use retry = 6 to..." or "To disable retries, set retry = false...") for even more variety.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f616474 and 3ab13a7.

📒 Files selected for processing (7)

• .changeset/bright-rabbits-jump.md
• docs/framework/react/guides/query-retries.md
• docs/framework/react/reference/useMutation.md
• docs/framework/react/reference/useQuery.md
• docs/framework/solid/reference/useQuery.md
• packages/query-core/src/__tests__/query.test.tsx
• packages/query-core/src/retryer.ts

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-11-22T09:06:05.219Z

Learnt from: sukvvon
Repo: TanStack/query PR: 9892
File: packages/solid-query-persist-client/src/__tests__/PersistQueryClientProvider.test.tsx:331-335
Timestamp: 2025-11-22T09:06:05.219Z
Learning: In TanStack/query test files, when a queryFn contains side effects (e.g., setting flags for test verification), prefer async/await syntax for clarity; when there are no side effects, prefer the .then() pattern for conciseness.

Applied to files:

• packages/query-core/src/__tests__/query.test.tsx

🧬 Code graph analysis (1)

packages/query-core/src/__tests__/query.test.tsx (1)

packages/query-core/src/query.ts (1)

• promise (198-200)

🪛 LanguageTool

docs/framework/react/guides/query-retries.md

[style] ~13-~13: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ll infinitely retry failing requests. - Setting retry = (failureCount, error) => ... ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (6)

docs/framework/solid/reference/useQuery.md (1)

279-279: ✓ Clear and accurate documentation update.

The note accurately documents the 1-based failureCount behavior when retry is a function, with appropriate placement in the parameter reference section.

docs/framework/react/reference/useMutation.md (1)

89-89: ✓ Consistent documentation across frameworks.

The addition mirrors the Solid documentation update and clearly states the 1-based failureCount behavior, maintaining consistency across framework-specific references.

.changeset/bright-rabbits-jump.md (1)

1-5: Changeset message clearly reflects the behavioral fix

The summary correctly states that the retry callback’s failureCount is now 1-based on the first failure, and it’s scoped as a patch for @tanstack/query-core, which matches the implementation and test coverage in this PR.

packages/query-core/src/retryer.ts (1)

169-178: 1-based failureCount for function retry is consistent with the rest of the API

Passing failureCount + 1 into the function retry branch makes the callback see [1, 2, …] for successive failures, which now aligns with how onFail and the public failureCount on query state are interpreted (1-based on first retryable failure).

One thing to double-check: retryDelay still receives the raw failureCount (0 on first failure) while the function retry now gets 1-based values. If the intention is that retryAttempt in retryDelay stays 0-based for backward compatibility, the current code is correct; if we eventually want both callbacks to be 1-based, that would require a separate, more breaking change (and doc update).

packages/query-core/src/__tests__/query.test.tsx (1)

156-181: New test accurately locks in 1-based failureCount behavior

This test exercises a function retry with a side-effectful queryFn and correctly asserts that failureCount values passed to the callback are [1, 2] before the successful third attempt. Timer usage (retryDelay: 1 + advanceTimersByTimeAsync(10)) is sufficient and keeps the test fast. Based on learnings, the async/await style here is appropriate given the side effects in the queryFn.

docs/framework/react/reference/useQuery.md (1)

83-88: Doc note correctly documents 1-based failureCount for function retry

The added bullet clearly states that, for function retry, the failureCount argument now starts at 1 on the first failed attempt, which matches the implementation and tests in this PR. Just make sure the same wording (or equivalent) is present in the other retry-related docs (useMutation, Solid useQuery, retries guide) so behavior is documented consistently across frameworks.

[KyungHwanKim-devs]

Hi! Thank you for the thoughtful review and checks.

The Docstring Coverage warning appears to come from CodeRabbit's internal pre-merge checks. This PR is mostly documentation updates with a small runtime tweak, and the touched files follow the existing style that generally doesn't use JSDoc, so it shows 0%. If maintainers would like this addressed, I'm happy to add docstrings in the relevant spots.

Could you please review the changes, and if everything looks good, approve? Thank you!

[TkDodo]

see:

• failureCount in the retry callback starts at zero #10017 (comment)