Can tRPC mutations be safely retried without duplicating writes?

Short answer

No. A tRPC mutation cannot be safely retried by default because the client cannot distinguish a write that committed from one whose response was lost. Retrying a non-idempotent procedure risks duplicating the side effect.

Confirmed behavior vs. likely explanation

Confirmed: tRPC does not implement its own mutation retry layer. Retry behavior is inherited from the React Query integration, which delegates to TanStack Query. TanStack Query does not retry mutations by default, unlike queries, because re-issuing a write-shaped request can duplicate the side effect.

Likely explanation: When a network drop or timeout occurs after the server has applied the mutation, the client receives a TRPCError or network error. tRPC error codes do not encode whether the write committed, so the client cannot infer server state from the error alone. This ambiguity is an application-level concern, not something the framework resolves.

Version-specific defaults to verify

The integration package name changed between major versions. Confirm which adapter your project imports before changing retry defaults:

tRPC version	React Query integration package
v10	@trpc/react-query
v11	@trpc/tanstack-react-query

Inspect the installed package and the options passed to useMutation to confirm that retry is not globally enabled:

npm ls @trpc/react-query @trpc/tanstack-react-query
grep -r "retry" src/ --include="*.ts" --include="*.tsx"

Recommended pattern: application-level idempotency

If a mutation must be retryable, make the procedure idempotent server-side. The client supplies a dedupe key, and the server enforces uniqueness before applying the write:

1. Generate a unique key on the client (for example, a UUID) and include it in the mutation input.
2. On the server, validate the key and check a dedupe store (such as a unique constraint or a short-lived cache) before executing the write.
3. If the key already exists, return the original result instead of re-applying the side effect.
4. Only then enable retry for that specific mutation, not globally.

What to avoid

Do not configure retries at the transport layer through custom links or batching for procedures that are not idempotent. Transport-layer retries re-issue the request and reintroduce duplicate-write risk. Likewise, errorFormatter and custom TRPCError data can carry metadata, but there is no standard framework-level idempotency-key mechanism, so do not assume one exists.

One diagnostic detail that changes the recommendation

Which tRPC major version and React Query integration package does your project use? The exact import path and option names differ between @trpc/react-query (v10) and @trpc/tanstack-react-query (v11), so the verification steps and any retry configuration must match the installed adapter.