0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00

fix(client-js): stop retrying state-changing requests by default (#30434)

> Opened by @factory-project:7d5175c3-3a20-42ac-aba9-756f183136f4

The JavaScript client retried every HTTP method the same way, so a
`POST`, `PUT`, `PATCH`, or `DELETE` that hit a server error was silently
re-sent up to four times. When the server had already committed the work
before failing, that replay duplicated side effects — agent generations,
workflow starts, and similar writes.

`BaseResource.request()` now resolves retries by method: `GET`, `HEAD`,
and `OPTIONS` keep the default of three attempts, while every other
method is attempted once unless the caller opts in with an explicit
`retries` count on the client or the call. Requests that pass no method
keep the previous read behavior.

Four observability queries only read server state even though they
travel as `POST`, so `aggregateTraces()`, `aggregateSpans()`,
`queryTraceThreads()`, and `querySpans()` keep the read default. An
explicit `retries` on the client still wins.

**Approved** — head `a2e46c41b1` (branch
`factory/issue-30404-3ca17cc5ca80`, base `5b7f1302`).

### Checks on this head

| Check | Result | Tests |
| --- | --- | --- |
| `@mastra/client-js` tests + typecheck (`npx vitest run`) | ✅ Passed |
910 passed across 48 files; typecheck no errors |
| Type-aware lint (`npx oxlint --type-aware .`) | ✅ Passed | 0 warnings,
0 errors |
| New tests on base code | ✅ Catches the bug | 4 of 4 write cases fail
on base, pass on head |
| Independent reproduction through the public client API against a real
500 server | ✅ Passed | base repeats POST/PATCH/PUT/DELETE and
`agent.generate` 4× each; head sends each once, GET still 4×, opt-in
counts unchanged |
| Changeset package validation | ✅ Passed | `@mastra/client-js` patch
accepted |

### Follow-ups

- `queryTraces()` is the one read-style `POST` left on the
single-attempt default
(`client-sdks/client-js/src/resources/observability.ts:338`). The four
queries the review named keep the read default, so the `@mastra/react`
hooks that pin React Query `retry: false` on them
(`client-sdks/react/src/hooks/traces/use-trace-aggregate.ts:30`,
`use-span-aggregate.ts:29`, `use-query-spans.ts:64`,
`use-query-threads.ts:67`) still get the client retry.
- `client-sdks/react/src/hooks/traces/use-trace-aggregate.ts:17` and
`use-span-aggregate.ts:16` say "the client already retries server
errors", which holds again for these endpoints on head `5ba90bf1`, so
those comments need no change.
- `docs/src/content/en/reference/client-js/observability.mdx:523` still
recommends `{ retries: 0, anchorRetryTimeoutMs: 0 }` for PUT feedback
replacement; `retries: 0` is now the PUT default, so only the
`anchorRetryTimeoutMs: 0` half still matters.

### Adversarial check

Most damaging reading — that this silently strips the only retry layer
from shipped `@mastra/react` observability queries and breaks the
contract those hooks document — fails on the evidence: the loss is
limited to read-style POST endpoints and is the method-based gating the
issue asked for, those hooks live in a package the approved plan scoped
out, and self-review treats adjacent hardening as a follow-up rather
than a blocking finding.

### Follow-up commit

`5ba90bf15a` adds the fix for the review
finding above: the four read-only observability queries pass `retries:
this.readRetries()` (new `BaseResource` helper, explicit client
`retries` wins), 5 new tests fail on `a2e46c41` and pass here, and the
playground-ui metrics tests that the write-only default broke pass
again.

Fixes #30404

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

ELI5: The JavaScript client used to resend failed requests up to three
times, even for actions that change data, like creating or deleting
things. Now, only read requests are retried by default. Change requests
are sent once unless the developer asks for retries.

## Summary

This pull request changes the default retry behavior of
`BaseResource.request()` in `@mastra/client-js`. The change stops
implicit retries of state-changing requests after a server error. A
server error does not show whether the server applied the change before
it failed, so a retry can repeat a side effect.

## Behavior change

- `GET`, `HEAD`, and `OPTIONS` keep the default of three retries.
- `POST`, `PUT`, `PATCH`, `DELETE`, and any other unrecognized method
send one attempt by default.
- Requests without a method use `GET`, so they keep the read-style
default of three retries. The method is normalized to upper case before
the lookup.
- An explicit `retries` value on the request overrides the client-level
value. The client-level value overrides the method default.
- Existing validation of the retry count is unchanged. A non-negative
safe integer is still required.
- Four read-only observability queries use `POST`: `aggregateTraces`,
`aggregateSpans`, `queryTraceThreads`, and `querySpans`. These queries
keep the read-style default of three retries. They do not follow the
write default.

## Implementation

- `client-sdks/client-js/src/resources/base.ts`:
- Adds a default of three retries for read methods and a set of read
methods (`GET`, `HEAD`, `OPTIONS`).
- Resolves retries in this order: request-level value, then client-level
value, then the method default. Other methods default to zero.
- Adds a protected `readRetries()` helper. It returns the
client-configured retry count, or three when none is set.
- `client-sdks/client-js/src/resources/observability.ts`: The four
observability queries listed above pass `readRetries()` as their retry
count. `aggregateTraces` still forwards its optional abort signal. The
other three calls do not add a signal option.
- `client-sdks/client-js/src/types.ts`: Updates the JSDoc for
`ClientOptions.retries` and `RequestOptions.retries`. The docs state the
read-only default. They also state that a per-request count overrides
the client count and enables retries for writes. Declarations are
unchanged.
- `client-sdks/client-js/src/resources/base.test.ts`: Adds 52 lines of
tests. The tests cover:
- One attempt for `POST`, `PATCH`, `PUT`, and `DELETE` after a 500
response, with no retry count configured.
  - Three attempts for read methods.
- Explicit client-level and request-level retry counts that enable
retries for writes.
- `client-sdks/client-js/src/resources/observability.test.ts`: Adds
tests that the four observability queries make four fetch attempts after
a server error. Adds tests that `retries: 0` on `aggregateTraces` limits
the request to one attempt. Moves the thread-query and span-query
request fixtures into their `describe` scopes. Payloads are unchanged.
- `client-sdks/client-js/src/resources/agent.client-tools.test.ts`:
Removes a mocked continuation response from one streaming test. The test
expects no recursive request.
- `.changeset/witty-wolves-write-once.md`: Adds a patch changeset for
`@mastra/client-js`.
- `docs/src/content/en/docs/server/mastra-client.mdx` and
`docs/src/content/en/reference/client-js/mastra-client.mdx`: Document
the per-method default. The reference page changes the `retries` default
to `3 for read requests, 0 for write requests`. The server page notes
that the listed observability queries keep the read default.

## Diff scope

The diff covers 9 files, with 200 insertions and 53 deletions. Six files
are in `client-sdks/client-js`, with 190 insertions and 51 deletions.
The changeset and two docs files make up the rest.

## Verification

The PR author reports that `npx vitest run` passed 910 tests across 48
files, with no typecheck errors. The author also reports that type-aware
lint and changeset validation passed. These results come from the PR
description. This summary did not rerun them.

## Notes

- The PR description lists `@mastra/react` hooks that use observability
POST endpoints as a follow-up. Hooks that set `retry: false`, and two
hook comments, may describe retry behavior that no longer applies. This
summary did not verify those files.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
This commit is contained in:
mastra-platform[bot] 2026-11-15 10:55:47 -08:00 • committed by GitHub
commit b666fdbf03
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 200 additions and 53 deletions