What causes "structuredOutput object is undefined" in mastra-ai/mastra?

Let the built-in fallback retry run — catch this error only at the outermost boundary; the function itself retries with JSON prompt injection.

mastra-ai/mastra · error · MastraError

STRUCTURED_OUTPUT_OBJECT_UNDEFINED

STRUCTURED_OUTPUT_OBJECT_UNDEFINED

Error message

structuredOutput object is undefined

What it means

After the first agent.generate() attempt, if the model resolves without throwing but produces no parseable structured object (result.object is undefined — e.g. empty or malformed JSON), tryGenerateWithJsonFallback converts that into a MastraError STRUCTURED_OUTPUT_OBJECT_UNDEFINED. This lets the caller get the json-prompt-injection retry instead of crashing later when reading result.object.

Source

Thrown at packages/core/src/agent/utils.ts:60

  options: AgentExecutionOptions<OUTPUT>,
): Promise<FullOutput<OUTPUT>> {
  if (!options.structuredOutput?.schema) {
    throw new MastraError({
      id: 'STRUCTURED_OUTPUT_OPTIONS_REQUIRED',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      text: 'structuredOutput is required to use tryGenerateWithJsonFallback',
    });
  }

  try {
    const result = await agent.generate(prompt, options);
    // Some models resolve without throwing but produce no parseable structured
    // object (empty/malformed JSON). Treat that the same as a thrown error so the
    // caller still gets the json-prompt-injection retry instead of a downstream
    // crash when it reads `result.object`. Mirrors tryStreamWithJsonFallback.
    if (result.object === undefined) {
      throw new MastraError({
        id: 'STRUCTURED_OUTPUT_OBJECT_UNDEFINED',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'structuredOutput object is undefined',
      });
    }
    return result;
  } catch (error) {
    if (!isStructuredOutputFormatError(error)) throw error;

    console.warn('Error in tryGenerateWithJsonFallback. Attempting fallback.', error);
    const result = await agent.generate(prompt, {
      ...options,
      structuredOutput: {
        ...options.structuredOutput,
        jsonPromptInjection:
          options.structuredOutput.jsonPromptInjection === 'inline' ||
          options.structuredOutput.jsonPromptInjection === 'system'

View on GitHub (pinned to 75dd419e61)

Solutions

Let the built-in fallback retry run — catch this error only at the outermost boundary; the function itself retries with JSON prompt injection.
Increase maxOutputTokens and/or use a model that reliably supports structured output/native tool calling.
Simplify or loosen the schema (fewer required fields, avoid deeply nested unions) to make valid JSON more likely.

Example fix

// before
const { object } = await tryGenerateWithJsonFallback(agent, prompt, opts); // crashes here if object undefined
// after
try {
  const { object } = await tryGenerateWithJsonFallback(agent, prompt, opts);
} catch (e) {
  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_OBJECT_UNDEFINED') {
    // model produced unparseable output after retries — handle or rethrow with context
  }
}

Defensive patterns

Strategy: try-catch

Type guard

function isStructuredResult<O>(r: FullOutput<O>): r is FullOutput<O> & { object: O } {
  return r.object !== undefined;
}

Try / catch

try {
  const result = await tryGenerateWithJsonFallback(agent, prompt, options);
  return result.object;
} catch (e) {
  if (e instanceof MastraError && e.id === 'STRUCTURED_OUTPUT_OBJECT_UNDEFINED') {
    // model output unparseable — retry with a stronger model or fall back to manual parsing
  }
  throw e;
}

Prevention

Use models known to follow JSON/schema instructions
Raise maxOutputTokens so JSON isn't truncated
Keep schemas simple; avoid deep nesting and exotic unions
Set jsonPromptInjection: 'system' for models that ignore user-level instructions

When it happens

Trigger: The model returns a response whose structured object cannot be parsed (empty content, non-JSON text, truncated JSON) during the initial structured-output generate attempt.

Common situations: Weak/small models ignoring the JSON schema instruction; very large schemas where output gets truncated; providers returning tool-call-free plain text; low maxOutputTokens cutting JSON mid-stream.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/c48863ab3bb73460. Report an issue: GitHub.