Bug Report

Package

@ai-sdk/google v3.0.29

Description

When calling generateText with both url_context and google_search Gemini grounding tools enabled, the SDK throws an AI_APICallError even though the Gemini API returns a 200 OK response. The failure is caused by a Zod validation error inside the SDK — it expects urlContextMetadata.urlMetadata to be an array, but the Gemini API returns "urlContextMetadata": {} (an empty object, without a urlMetadata key) when the model used Google Search but did not actually fetch any URLs via the URL context tool.

Error

AI_APICallError: Invalid JSON response
  caused by: AI_TypeValidationError: Type validation failed
    caused by: ZodError: [
      {
        "expected": "array",
        "code": "invalid_type",
        "path": ["candidates", 0, "urlContextMetadata", "urlMetadata"],
        "message": "Invalid input: expected array, received undefined"
      }
    ]

Reproduction

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

const result = await generateText({
  model: google("gemini-3-flash-preview"), // or gemini-3-flash-preview
  tools: {
    url_context: google.tools.urlContext({}),
    google_search: google.tools.googleSearch({}),
  },
  prompt: "Find the official Facebook page for the brand Altuzarra.",
  temperature: 0.0,
});

When the model uses only google_search grounding (not URL fetching), the Gemini API response contains:

{
  "candidates": [
    {
      "urlContextMetadata": {}
    }
  ]
}

The SDK's internal Zod schema validates urlContextMetadata.urlMetadata as a required array, which fails when the field is absent.

Actual Gemini Response (trimmed)

{
  "candidates": [
    {
      "content": { "parts": [{ "text": "..." }], "role": "model" },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": ["Altuzarra brand Facebook", "..."]
      },
      "urlContextMetadata": {}
    }
  ],
  "modelVersion": "gemini-3-flash-preview"
}

Note: urlContextMetadata is present but empty — no urlMetadata array inside.

Expected Behavior

The SDK should handle an empty urlContextMetadata: {} gracefully (treating urlMetadata as an empty array or optional field) rather than throwing a validation error, since the Gemini API legitimately returns this shape when the URL context tool was registered but not invoked.

Environment

• @ai-sdk/google: 3.0.29
• ai: (Vercel AI SDK)
• Model: gemini-3-flash-preview (also reproducible with gemini-2.0-flash)
• Node.js: 20.x

Workaround

Remove url_context from the tools list when you only need google_search grounding. This prevents Gemini from returning urlContextMetadata entirely.

Raw logs

raw_logs.txt