Gemini Function Call Schema Invalid (400 INVALID_ARGUMENT)
Your function declaration uses features Gemini's OpenAPI 3.0 subset doesn't support. Common triggers: anyOf/oneOf at wrong level, unsupported format values, missing types, or migrating an OpenAI schema without translation.
Quick Fix (TL;DR)
Gemini uses an OpenAPI 3.0 subset: types = string/integer/number/boolean/array/object, plus
Gemini uses an OpenAPI 3.0 subset: types = string/integer/number/boolean/array/object, plus enum, nullable, required, description. Not supported: oneOf, allOf, $ref, most format values, string constraints. Use google.genai.types.Schema or plain dicts respecting the subset.
The Error Messages You're Seeing
Response body variants
HTTP/1.1 400 Bad Request
{
"error": {
"code": 400,
"message": "Invalid FunctionDeclaration: field 'parameters.
properties.email.format' has unsupported value 'email'.",
"status": "INVALID_ARGUMENT"
}
}
Variants:
"Unknown field 'oneOf' in Schema"
"Field 'parameters' missing required 'type'"
"Unsupported schema type: 'null'"
"'additionalProperties' not supported in this context"
"Invalid enum value type: expected STRING"Supported vs Unsupported (OpenAPI Subset)
| Feature | Supported | Notes |
|---|---|---|
| type: string, integer, number, boolean, array, object | Yes | Core types |
| enum (on strings) | Yes | Great for constrained choices |
| nullable: true | Yes | Preferred over union types |
| description | Yes | Improves accuracy |
| required (array of prop names) | Yes | List required fields |
| propertyOrdering | Yes | Recommended for consistency |
| anyOf | Yes (limited) | Nested only, avoid at root |
| oneOf, allOf, $ref | No | Not supported |
| format: date-time, enum values on number | Partial | Only some formats work |
| format: email, uuid, uri | No | String constraints unsupported |
| minLength/maxLength/pattern | No | Not supported |
| additionalProperties | No | Silently ignored |
What Actually Causes This Error
35%
Ported OpenAI schema directlyOpenAI's strict subset differs; format:"email" and similar reject.
22%
Pydantic auto-generated schemaEmits $ref, oneOf, format values Gemini doesn't accept.
18%
Missing type on parameters rootMust be
type: "object" at parameters level.15%
oneOf / allOf for union typesUnion of two types → use nullable + single type instead.
10%
Nested $ref definitionsReused sub-schemas via $ref/$defs — must be inlined.
Fixes That Work (Tested Nov 2026)
1Correct Function Declaration
Python · valid Gemini function schema
from google import genai
from google.genai import types
client = genai.Client()
get_weather = types.FunctionDeclaration(
name="get_weather",
description="Get current weather for a location.",
parameters=types.Schema(
type="OBJECT",
properties={
"location": types.Schema(
type="STRING",
description="City name, e.g. Karachi"
),
"units": types.Schema(
type="STRING",
enum=["celsius", "fahrenheit"],
description="Temperature units"
)
},
required=["location", "units"],
property_ordering=["location", "units"]
)
)
tools = types.Tool(function_declarations=[get_weather])
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Weather in Karachi in celsius?",
config=types.GenerateContentConfig(tools=[tools])
)
# Extract function call
for part in response.candidates[0].content.parts:
if part.function_call:
print(part.function_call.name, part.function_call.args)
2OpenAI → Gemini Schema Translator
Python · migration helper
GEMINI_TYPE_MAP = {
"string": "STRING",
"integer": "INTEGER",
"number": "NUMBER",
"boolean": "BOOLEAN",
"array": "ARRAY",
"object": "OBJECT",
}
UNSUPPORTED_FORMATS = {"email", "uri", "uuid", "hostname", "ipv4", "ipv6"}
def openai_to_gemini_schema(schema):
"""Convert OpenAI-style schema dict to Gemini-compatible."""
if not isinstance(schema, dict):
return schema
result = {}
# Handle union types (["string", "null"] → nullable string)
t = schema.get("type")
if isinstance(t, list):
non_null = [x for x in t if x != "null"]
if non_null:
result["type"] = GEMINI_TYPE_MAP.get(non_null[0], non_null[0].upper())
if "null" in t:
result["nullable"] = True
elif t:
result["type"] = GEMINI_TYPE_MAP.get(t, t.upper())
# Drop unsupported keywords
for k in ("description", "enum", "required", "nullable"):
if k in schema:
result[k] = schema[k]
# Only keep supported format values
fmt = schema.get("format")
if fmt and fmt not in UNSUPPORTED_FORMATS:
if fmt in ("date-time", "date", "enum", "int32", "int64"):
result["format"] = fmt
# Recurse into properties and items
if "properties" in schema:
result["properties"] = {
k: openai_to_gemini_schema(v)
for k, v in schema["properties"].items()
}
if "items" in schema:
result["items"] = openai_to_gemini_schema(schema["items"])
return result
# Usage: migrate existing OpenAI-style tools
gemini_params = openai_to_gemini_schema(openai_function["parameters"])
Type names: uppercase strings vs enum
Gemini's schema types use UPPERCASE ("STRING", "OBJECT") when serialized to JSON, matching OpenAPI's Type enum. The SDK's types.Schema class accepts either — but raw dicts must use uppercase.
3Debug Common Failures
Python · common fixes side by side
# WRONG — Pydantic often emits these
bad_schema = {
"type": "object", # should be OBJECT (uppercase)
"properties": {
"email": {
"type": "string",
"format": "email" # NOT SUPPORTED
},
"age": {
"anyOf": [ # unsupported at property level
{"type": "integer"},
{"type": "null"}
]
}
},
"additionalProperties": False # silently ignored
}
# RIGHT
good_schema = {
"type": "OBJECT",
"properties": {
"email": {
"type": "STRING",
"description": "User's email address"
},
"age": {
"type": "INTEGER",
"nullable": True,
"description": "Age in years, if known"
}
},
"required": ["email"],
"property_ordering": ["email", "age"]
}
Preventing This Error Going Forward
- Use
types.Schemafor type-checked construction. - Uppercase types in raw dicts. STRING, OBJECT, INTEGER.
- Prefer
nullable: trueover union types. - Skip unsupported format values. email, uuid — validate client-side.
- Don't rely on
additionalProperties. Silently ignored. - Use
property_orderingfor consistent output shapes. - Translate OpenAI schemas via helper. Don't paste directly.
SK
Tested by Sana K.
Researcher · AI Error Hub
Researcher · AI Error Hub
Last verified: Nov 15, 2026 · SDK: google-genai 0.8+
Frequently Asked Questions
Yes — the SDK's from_callable or Pydantic-to-Schema helpers translate most of it. For complex models, verify the generated schema doesn't emit $ref, oneOf, or unsupported format values. Sanitize before use.
Yes — the model uses ordering as a hint for output field order. Especially useful for controlled generation with response_schema. Consistent ordering improves downstream parsing reliability.
Two ways. (1) Omit from required array — field may not appear. (2) Include in required with nullable: true — field always appears but may be null. Option 2 gives more consistent parsing.
Yes — the model may return multiple function_call parts in a single candidate. Iterate all parts and dispatch each. Configure via tool_config with mode ANY, AUTO, or NONE.
Gemini accepts a subset of OpenAPI 3.0 (which overlaps JSON Schema). Some full JSON Schema features ($ref, allOf, oneOf, complex format) don't work. Stick to the documented subset.