Skip to content

[BUG] Top-level array structured output silently returns [] for arrays of primitives #23980

Closed

Description

@BlueX888

Describe the Bug

Structured output with a top-level array schema (z.array(z.string()), z.array(z.number()), or any array whose elements are not non-empty objects) silently resolves response.object to [], even though response.text contains the full, valid JSON and validation passes.

ArrayFormatHandler.processPartialChunk (packages/core/src/stream/base/output-format-handlers.ts:458) only ever pushes an element when

element && typeof element === 'object' && Object.keys(element).length > 0

String, number, boolean and null elements fail that predicate on every text-delta, so the accumulated filtered array stays empty. Because z.array(z.string()).safeParse([]) succeeds, the empty array is treated as a valid final result and the loss is completely silent. Arrays of non-empty objects (z.array(z.object({...}))) are unaffected, which is why the existing tests (which all use z.array(z.object(...))) do not catch it.

Steps To Reproduce

Drive MastraModelOutput in direct structured-output mode with a top-level array schema and a stream whose model text is the wrapped array {"elements":["alpha","beta"]}:

import { ReadableStream } from 'node:stream/web';
import { z } from 'zod';
import { MessageList } from '<repo>/packages/core/src/agent/message-list/index.ts';
import { ChunkFrom } from '<repo>/packages/core/src/stream/types.ts';
import { MastraModelOutput } from '<repo>/packages/core/src/stream/base/output.ts';

const runId = 'run-1';
const json = '{"elements":["alpha","beta"]}';
const text = (t: string) => ({ runId, from: ChunkFrom.AGENT, type: 'text-delta', payload: { id: 't1', text: t } });
const chunks = [
  text(json.slice(0, 12)),
  text(json.slice(12)),
  { runId, from: ChunkFrom.AGENT, type: 'text-end', payload: { id: 't1' } },
  { runId, from: ChunkFrom.AGENT, type: 'step-finish', payload: {
      id: 's1', output: { steps: [], usage: { inputTokens: 1, outputTokens: 2, totalTokens: 3 } },
      stepResult: { reason: 'stop', warnings: [], isContinued: false }, metadata: {}, messages: { nonUser: [], all: [] } } },
  { runId, from: ChunkFrom.AGENT, type: 'finish', payload: {
      id: 'f1', output: { steps: [], usage: { inputTokens: 1, outputTokens: 2, totalTokens: 3 } },
      stepResult: { reason: 'stop', warnings: [], isContinued: false }, metadata: {}, messages: { nonUser: [], all: [] } } },
];

const output = new MastraModelOutput({
  model: { modelId: 'm', provider: 'openai', version: 'v3' },
  stream: new ReadableStream<any>({ start(c) { for (const ch of chunks) c.enqueue(ch); c.close(); } }),
  messageList: new MessageList({ threadId: 't' }),
  messageId: 'msg-1',
  options: { runId, isLLMExecutionStep: true, resolveFinalPromises: true, structuredOutput: { schema: z.array(z.string()) } },
});

for await (const _ of output.fullStream) {}
console.log('text:', JSON.stringify(await output.text));
console.log('object:', JSON.stringify(await output.object));

Swapping the schema for z.array(z.number()) or z.array(z.object({ a: z.string() })) and the text accordingly shows the same contrast.

Link to Minimal Reproducible Example

Reproduction is the script inlined above (run from inside the repo with the quoted import paths); it is also reproducible as an in-repo Vitest test calling ArrayFormatHandler.processPartialChunk directly with the same accumulated text. No separate public repo was created.

Actual Output

Verifier 1 (end-to-end via MastraModelOutput):

z.array(z.string()) => text: "{\"elements\":[\"alpha\",\"beta\"]}"  object: []
z.array(z.number()) => text: "{\"elements\":[1,2]}"  object: []
z.array(z.object({a:z.string()})) => text: "{\"elements\":[{\"a\":\"x\"},{\"a\":\"y\"}]}"  object: [{"a":"x"},{"a":"y"}]
single-delta object-chunks: [[]] ; single-delta final object: []
(WITH FIX) z.array(z.string()) object: ["alpha","beta"] ; z.array(z.number()) object: [1,2]

Verifier 2 (in-repo Vitest, unit + end-to-end):

UNIT string object-result: []
UNIT number object-result: [1,2] -> actually []
E2E text: "{\"elements\":[\"alpha\",\"beta\"]}"
E2E object: []
(UNIT string object chunks: [[]])
With the candidate fix: object-result: ["alpha","beta"], E2E object: ["alpha","beta"]

Expected Behavior

response.object should contain the model's array items, i.e. ["alpha","beta"] for the reproduction above.

Concrete basis:

  • packages/core/src/stream/base/schema.ts:100-113 wraps any array schema as { type: 'object', properties: { elements: { type: 'array', items: innerElement } }, required: ['elements'] } with outputFormat: 'array', and getResponseFormat/the unwrap contract promise the underlying array elements back to the caller.
  • docs/src/content/en/docs/agents/structured-output.mdx states structured output "lets an agent return an object that matches the shape defined by a schema" and that you "Access the validated, typed result through response.object", and shows top-level schema: z.array(...) examples.
  • The handler's own docstring (output-format-handlers.ts:417) says it "unwraps them and filters incomplete elements" — it is not supposed to drop completed primitive elements.
  • The sibling ObjectFormatHandler in the same file drops no fields at all.
  • Upstream AI SDK 5 (origin of the {elements: [...]} wrapper) pushes every element that passes safeValidateTypes against the element schema.
  • Validated structured output masks the bug because z.array(z.string()).safeParse([]) succeeds.

Environment Information

  • Package: @mastra/core 1.67.0-alpha.4 (monorepo source build)
  • Commit: 3fc8c2d35f724c3648150b29e50cf61a9360b274 (branch main)
  • Node: v22.23.2
  • OS: macOS (Darwin 25.6.0, arm64)
  • LLM Provider: n/a for the reproduction (mocked stream); mode is direct structured output (isLLMExecutionStep: true)

Root Cause

packages/core/src/stream/base/output-format-handlers.ts:458 — the non-last-element branch of ArrayFormatHandler.processPartialChunk pushes an element only when element && typeof element === 'object' && Object.keys(element).length > 0. Primitive elements (string/number/boolean/null) never satisfy this on any text-delta, so the filtered array remains empty and the final object resolves to []. Secondarily, validateAndTransformFinal validates this.textPreviousFilteredArray rather than the parsed final text, so a result that dropped everything can still validate as a valid empty array.

Offer To Fix

This repo's bug report template notes a maintainer must approve the report before community members can open PRs, so happy to be assigned and then open a PR with the fix (relax the guard to skip only null/undefined, keeping the empty-object guard solely for the incomplete trailing element, and validate the actual final text rather than the previously filtered array).

Related References

No duplicate or overlapping issue/PR found (searched "structured output array", "z.array", "array of strings structured output", "processPartialChunk", "elements array empty"). Closest but distinct: #18758 (Array textStream emits invalid JSON when the first object chunk already has elements) — a different defect in array-format streaming.

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

Activity

  1. dane-ai-mastra commented on Sep 15, 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. dane-ai-mastra commented on Sep 15, 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

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions