[BUG] JSONDecodeError when using Gemini models with free tier API key

[jztan]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.12.0

Python Version

3.10.17

Operating System

macOS 26.0.1

Installation Method

pip

Steps to Reproduce

1. Create a Google AI Studio free tier API key from https://aistudio.google.com/
2. Use the API key with GeminiModel in Strands
3. Create an agent with tools
4. Invoke the agent with a query that triggers tool use

Minimal reproduction code:

import os
from strands import Agent, tool
from strands.models.gemini import GeminiModel

@tool
def calculator(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))

model = GeminiModel(
    client_args={"api_key": os.getenv("GOOGLE_API_KEY")},
    model_id="gemini-2.0-flash",
    params={"max_output_tokens": 500, "temperature": 0.7}
)

agent = Agent(model=model, tools=[calculator])
response = agent("What is 25 * 4?")  # Crashes here

Expected Behavior

When the Gemini API returns an error (authentication failure, invalid response, etc.), Strands should:

1. Catch the error gracefully
2. Provide a clear error message (e.g., "API authentication failed", "Invalid API response", or "Gemini API configuration error")
3. Optionally raise a more specific exception like ModelThrottledException for rate limits
4. NOT crash with a generic JSONDecodeError that doesn't indicate the root cause

Actual Behavior

Strands crashes with:
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

This error is unhelpful because it doesn't indicate the root cause (API authentication, billing, permissions, rate limiting, etc.).

Full traceback:
Traceback (most recent call last): File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 146, in event_loop_cycle async for tool_event in tool_events: File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 406, in _handle_tool_execution async for event in events: File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 209, in recurse_event_loop async for event in events: File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 110, in event_loop_cycle async for model_event in model_events: File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 316, in _handle_model_execution raise e File ".venv/lib/python3.10/site-packages/strands/event_loop/event_loop.py", line 264, in _handle_model_execution async for event in stream_messages(agent.model, agent.system_prompt, agent.messages, tool_specs): File ".venv/lib/python3.10/site-packages/strands/event_loop/streaming.py", line 351, in stream_messages async for event in process_stream(chunks): File ".venv/lib/python3.10/site-packages/strands/event_loop/streaming.py", line 308, in process_stream async for chunk in chunks: File ".venv/lib/python3.10/site-packages/strands/models/gemini.py", line 411, in stream message = json.loads(error.message) File "/usr/lib/python3.10/json/init.py", line 346, in loads return _default_decoder.decode(s) File "/usr/lib/python3.10/json/decoder.py", line 337, in decode obj, end = self.raw_decode(s, idx=_w(s, 0).end()) File "/usr/lib/python3.10/json/decoder.py", line 355, in raw_decode raise JSONDecodeError("Expecting value", s, err.value) from None json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Error location: strands/models/gemini.py:411

Additional Context

Google AI Studio Free Tier Limits:

• gemini-2.0-flash: 15 RPM, 200 RPD
• gemini-2.0-flash-lite: 30 RPM, 200 RPD

Note: The error is NOT related to rate limiting, as ModelThrottledException is not raised. This appears to be an API authentication or configuration issue that should be caught and reported clearly.

Error occurs intermittently, possibly related to:

• Newly created API keys (activation delay)
• Google Cloud project configuration
• Billing setup requirements (even for free tier)
• Regional restrictions

Tested with both:

• gemini-2.0-flash
• gemini-2.0-flash-lite

Both models exhibit the same error, confirming it's not model-specific.

Dependencies:

• strands-agents: 1.12.0
• google-genai: 1.43.0

Possible Solution

The error occurs at strands/models/gemini.py:411:

message = json.loads(error.message)
This assumes error.message is always valid JSON. When the Google Gemini API returns an error with an empty or non-JSON message (common with authentication failures), this line crashes. Suggested fix:
# Current code (line 411):
message = json.loads(error.message)

# Suggested fix:
try:
    message = json.loads(error.message) if error.message else {}
except json.JSONDecodeError:
    # Fallback for non-JSON error messages
    message = {
        "error": str(error.message) or "Unknown Gemini API error",
        "hint": "Check API key configuration, billing setup, and API enablement"
    }
    logger.warning(f"Gemini API returned non-JSON error: {error.message}")

This would provide a more helpful error message to users and prevent crashes.

[dbschmigelski]

Hi, marking this as something that we'd be open to see contributed by the community.

To start, I would say, lets do

try:
    message = json.loads(error.message) if error.message else {}
except json.JSONDecodeError:
    logger.warning(f"Gemini API returned non-JSON error: {error.message}")
    raise

Preventing all crashes in this case feels too broad to me. I would rather identify specific cases, perhaps inspecting the message if needed, and handle them directly.