feat(ai): add retry support to onError callback in generateObject/streamObject

[fveiraswww]

Background

currently maxRetries only handles model api errors. However, generateObject and streamObject can fail for other reasons (e.g. schema validation errors, JSON parsing errors). this pr enables developers to implement custom retry logic for these cases

Summary

adds support for custom retry logic via the onError callback in generateObject and streamObject

• added retry function to onError callback that accepts partial options: { ...originalOptions, ...newOptions }
• wired onError callback into the parseAndValidateObjectResultWithRepair catch block to enable retries on schema validation failures
• extracted StreamObjectOptions to stream-object-options.ts
• extracted GenerateObjectOptions to generate-object-options.ts
• created StreamObjectReturnType helper type for better type inference
• added onError parameter doc to generate-object reference (prev undocumented)
• updated onError parameter doc in stream-object to include retry function

example usage:

const result = await generateObject({
  model: 'xai/grok-3-beta',
  schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(
          z.object({
            name: z.string(),
            amount: z.string(),
          }),
        ),
        steps: z.array(z.string()),
      }),
  }),
  prompt: 'Generate a lasagna recipe',
  onError: async ({ error, retry }) => {
    // Retry with adjusted temperature
    if (shouldRetry(error)) {
      return await retry({ temperature: 0.5 });
    }
  },
});

Manual Verification

tested basic retry functionality with generateObject and streamObject

Checklist

• Tests have been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• Documentation has been added / updated (for bug fixes / features)
• Formatting issues have been fixed (run pnpm prettier-fix in the project root)
• I have reviewed this pull request (self-review)

Future Work

Related Issues

[lgrammel]

We have a repair function that you can use: https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data#repairing-invalid-or-malformed-json

The reason a repair function approach was taken is that it gives you more control.

You can also use streamText with automated roundtrips for error cases and prepareStep for setting temperature.

[fveiraswww]

thanks @lgrammel! I know about experimental_repairText, but you're still relying on an LLM that can make mistakes. In this case, with streamObject and generateObject you can't use step options

the temperature setting is just an example, on retry you actually have access to StreamObjectOptions / GenerateObjectOptions

It's more of a double-check: if parseAndValidateObjectResultWithRepair fails, you trigger onError with the option to retry