Skip to content

[BUG] Array structured output textStream/elementStream keep the stale partial element when a later chunk completes it in place #25208

Closed

Description

@BlueX888

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:

  • textStream emits [{"a":1},{"a":2,"b":4}] while the final validated object is [{"a":1,"b":2},{"a":2,"b":4}] — the "b":2 field is missing from the streamed first element.
  • elementStream likewise 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 — in createJsonTextStreamTransformer, 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 — elementStream only publishes elements past publishedElements, 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

  1. dane-ai-mastra commented on Sep 26, 2026

    @dane-ai-mastra
    Contributor

    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.

  2. mastra-platform commented on Sep 27, 2026

    @mastra-platform
    Contributor
    Type bug — array structured-output textStream/elementStream emit stale partial elements that later chunks complete in place
    Route Plan fix
    Severity 🟡 medium — streamed array diverges from the final validated object (fields dropped); final object stays correct
    Confidence high — the append-only logic is plainly visible in the code and matches the reported output exactly
    Effort low — two localized transformers in packages/core/src/stream/base; the reporter's PR #25138 already has tests
    Impact medium — anyone rendering or persisting array streams from token-level providers loses fields; workaround is to use the final object
    Next step Implement hold-back-trailing-element fix (review/reopen #25138) with transformer + e2e regression tests

    Understanding

    Array-schema streaming assumes each new object chunk 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.ts createJsonTextStreamTransformer: 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) sets previousArrayLength from that chunk. The incremental loop then emits only i >= 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.ts elementStream: publishes chunk.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

    • I accepted the reporter's failing tests as the reproduction because the code path is deterministic and provider-independent. I did not run a weather-agent repro.
    • Elements should only be published once complete; re-emitting a corrected element isn't possible for a concatenated text stream.

    Open questions

    • For 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 createJsonTextStreamTransformer the 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 on main 4c90e6d.

  3. added a commit that references this issue on Sep 27, 2026
    d284118
  4. dane-ai-mastra commented on Sep 28, 2026

    @dane-ai-mastra
    Contributor

    This issue has been resolved and is available in the latest stable release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    @mastra/coreIssues whose primary fix belongs in @mastra/coreAgentsIssues regarding Mastra's Agent primitiveeffort:lowimpact:mediumTriage impact: mediumstatus: auto-triagedIssue has been auto-triaged

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions