Repository navigation
Description
Describe the Bug
When an agent streams a structured output whose schema is an array (structuredOutput: { schema: z.array(...) }) with token-by-token provider streaming, each object chunk carries the array parsed so far. The trailing element of a chunk is still partial and a later chunk completes it in place (same index, more fields) instead of appending a new index. Both array streams keep the stale partial version of that element:
textStreamemits[{"a":1},{"a":2,"b":4}]while the final validated object is[{"a":1,"b":2},{"a":2,"b":4}]— the"b":2field is missing from the streamed first element.elementStreamlikewise publishes the stale{a:1}instead of{a:1,b:2}.
The streamed array therefore diverges from the final validated object that Mastra itself returns, so consumers that render or persist the stream (UI element lists, downstream tooling) silently lose fields.
Steps To Reproduce
End to end, with any provider that streams the JSON token by token (reproduced with synthetic text-delta chunks, so it is provider-independent):
import { MastraModelOutput } from '@mastra/core/stream';
import { z } from 'zod';
const deltas = ['{"elements":', '[{"a":1', ',"b":2}', ',{"a":2,"b":4}', ']}'];
// feed deltas as text-delta chunks + text-end/finish into MastraModelOutput with
// structuredOutput: { schema: z.array(z.object({ a: z.number(), b: z.number() })) }
for await (const text of output.textStream) { /* accumulates */ }
// -> '[{"a":1},{"a":2,"b":4}]' (missing "b":2 on the first element)
// final validated object: '[{"a":1,"b":2},{"a":2,"b":4}]'Unit-level, against createJsonTextStreamTransformer directly (no provider involved) — feed it three object chunks, [{a:1}], [{a:1,b:2}], [{a:1,b:2},{a:2,b:4}]; the joined text is [{"a":1},{"a":2,"b":4}].
The four regression tests that encode exactly this (two transformer-level, two end-to-end textStream/elementStream) are in the linked PR below and fail on current main (4c90e6d):
cd packages/core && pnpm exec vitest run src/stream/base/output-format-handlers.test.ts src/stream/base/output.test.ts
Test Files 2 failed (2)
Tests 4 failed | 103 passed (107)
AssertionError: expected '[{"a":1},{"a":2,"b":4}]' to be '[{"a":1,"b":2},{"a":2,"b":4}]' // Object.is equality
and for elementStream, a diff showing - "b": 2 missing from the first published element.
Link to Minimal Reproducible Example
#25138 — the PR's test additions are the minimal reproduction (they fail on unpatched main, pass with the fix); see packages/core/src/stream/base/output-format-handlers.test.ts and packages/core/src/stream/base/output.test.ts in the diff.
Expected Behavior
Both textStream and elementStream should end with the same array as the final validated object: [{"a":1,"b":2},{"a":2,"b":4}], with each published element complete. Concretely: the schema z.object({ a: z.number(), b: z.number() }) requires b on every element, and the final object does contain b: 2 on the first element — the streams are the only place it is dropped. An element that a later chunk completes in place should be published once complete (or re-emitted), not left as the first partial parse.
Environment Information
OS: macOS 26.6.2 (arm64)
Node: v22.23.2
pnpm: 11.21.0
Repo: mastra-ai/mastra @ main 4c90e6d5487f2f72c1fdf3f7d522776452c16290 (2026-09-25)
@mastra/core workspace version: 1.72.0-alpha.0
vitest: 4.1.11
LLM Provider: none needed — reproduced at unit level (transformer fed object chunks) and with synthetic text-delta chunks; provider-independent
Root cause
With an array schema, the streaming code assumes new chunks only append elements:
packages/core/src/stream/base/output-format-handlers.ts:796-801— increateJsonTextStreamTransformer, the second-chunk path replays the buffered first chunk verbatim and sets the emitted length from it, so the partial trailing element of the first chunk is emitted as-is.packages/core/src/stream/base/output-format-handlers.ts:809-817— the incremental loop only emits elements at indices past the previously seen array length, so an element completed in place at an existing index is never re-emitted.packages/core/src/stream/base/output.ts:1839-1841—elementStreamonly publishes elements pastpublishedElements, for the same reason.
The fix direction (holding back the trailing element of each chunk until a following element or the stream end proves it complete) is implemented in the linked PR.
Verification
- I have searched the existing issues to make sure this is not a duplicate
- I have included sufficient information for the team to reproduce and understand the issue
I have a fix ready in #25138 (closed for lacking a linked issue — reopening it once this issue is linked). Happy to reopen the PR with this fix once this issue is linked, or to be assigned if you prefer to take it.
Activity
dane-ai-mastra commentedon Sep 26, 2026
Thank you for opening this issue. It is waiting for maintainer triage or approval.
Please wait until maintainers remove the triage or approval label before opening a pull request.
mastra-platform commentedon Sep 27, 2026
textStream/elementStreamemit stale partial elements that later chunks complete in placeobjectstays correctpackages/core/src/stream/base; the reporter's PR #25138 already has testsobjectUnderstanding
Array-schema streaming assumes each new
objectchunk only appends elements. With token-level deltas, the partial JSON parser yields the trailing element partially (e.g.{a:1}), and a later chunk completes it at the same index ({a:1,b:2}). Nothing ever re-emits it.packages/core/src/stream/base/output-format-handlers.tscreateJsonTextStreamTransformer: the path that replays the buffered first chunk (added for [BUG] Array textStream emits invalid JSON when the first object chunk already has elements #18758) setspreviousArrayLengthfrom that chunk. The incremental loop then emits onlyi >= previousArrayLength. So the partial trailing element is written and stays frozen. Because the output is concatenated JSON text, it can't be retracted.packages/core/src/stream/base/output.tselementStream: publisheschunk.object[publishedElements]as soon as the index exists. Same stale-partial problem.Suggested direction: only emit or publish an element once a later element exists (which proves it is complete), then flush the trailing element(s) from the last chunk on stream end. This keeps the #18758 guarantee (the output stays valid, well-formed JSON). The reporter's #25138 implements exactly this and includes 4 regression tests.
Related: #18758 (earlier invalid-JSON fix in the same transformer), PR #25138 (proposed fix).
Assumptions
Open questions
elementStream, holding back the trailing element delays it by one element. Maintainers should confirm that latency trade-off is acceptable versus publishing validated-complete elements only.Reproduction
I didn't run it myself; I checked it by reading the code. Feeding
createJsonTextStreamTransformerthe object chunks[{a:1}],[{a:1,b:2}],[{a:1,b:2},{a:2,b:4}]produces[{"a":1},{"a":2,"b":4}]: the replay emits{a:1}and sets length=1, then only index 1 is emitted afterwards. The reporter's tests in #25138 fail onmain4c90e6d.fix(core): hold back partial trailing array elements in textStream/el…
dane-ai-mastra commentedon Sep 28, 2026
This issue has been resolved and is available in the latest stable release.