Repository navigation
Description
🔴 Required Information
Describe the Bug:
FirestoreSessionService writes app: and user: state to Firestore natively, so it can keep rich types such as datetime. Before writing, _encode_firestore_value only reshapes dicts and lists. Every other value goes to the Firestore client unchanged. The client can only encode None, bool, int, float, str, bytes, datetime.datetime, lists, dicts and its own types. Anything else raises TypeError: Cannot convert to a Firestore Value, including a datetime.date, uuid.UUID, decimal.Decimal, a plain Enum or a Pydantic model.
The error happens inside the write transaction:
append_eventraises, and the event is never added to the session. The turn is lost.create_sessionraises when the initial state contains such a value.
The same value works everywhere else:
- Under a session-level key in Firestore, because that bucket goes through
_session_util.make_json_safe_state. - Under
app:anduser:inDatabaseSessionServiceandSqliteSessionService. Both store it in JSON-safe form, for example"2024-06-15".
So an agent that works on the database or SQLite backend fails once it is switched to Firestore. #7826 made this same fix for VertexAiSessionService. Its description lists Firestore as already coercing state, which is true only for session-level state.
Steps to Reproduce:
pip install google-adk[gcp].- Run the script under Minimal Reproduction Code. It mocks the Firestore client, but the transaction's
set()runs the client's realpbs_for_set_no_merge, which is whatTransaction.set()runs, so no Firestore project is needed. - Or with a live Firestore database: in a tool, set
tool_context.state["user:due"] = datetime.date.today(), then run the agent withFirestoreSessionService.
Expected Behavior:
The value is stored in the JSON-safe form that the session bucket and the other backends use ("2026-11-18", the UUID string, "1.50"), and the event is appended.
Observed Behavior:
session state with a date: stored
user: state with a date: append_event failed: TypeError('Cannot convert to a Firestore Value', datetime.date(2026, 11, 18), 'Invalid type', <class 'datetime.date'>)
events: 0
Environment Details:
- ADK Library Version (pip show google-adk): 2.14.1 (
mainat c74df83) - google-cloud-firestore: 2.34.1
- Desktop OS: Windows 11 (the bug isn't OS-specific)
- Python Version (python -V): 3.12.0
Model Information:
- Are you using LiteLLM: No
- Which model is being used: N/A (session service only)
🟡 Optional Information
Regression:
No. App and user state have been written natively since nested-array support was added. That change handled nested lists but not other non-native values.
Minimal Reproduction Code:
import asyncio
import datetime
from unittest import mock
from google.adk.events.event import Event
from google.adk.events.event_actions import EventActions
from google.adk.integrations.firestore import FirestoreSessionService
from google.cloud.firestore_v1 import _helpers
# A mocked client whose transaction.set() encodes the document exactly as the
# real Transaction.set() does, so unsupported values fail the same way.
client = mock.MagicMock()
doc = mock.MagicMock(exists=False)
doc.to_dict.return_value = {}
client.collection.return_value.document.return_value.get = mock.AsyncMock(return_value=doc)
ref = client.collection.return_value.document.return_value.collection.return_value.document.return_value
ref.get = mock.AsyncMock(return_value=doc)
ref.collection.return_value.document.return_value.get = mock.AsyncMock(return_value=doc)
client.transaction.return_value.set.side_effect = (
lambda _ref, data, **_: _helpers.pbs_for_set_no_merge("projects/p/databases/(default)/documents/c/d", data)
)
async def main():
service = FirestoreSessionService(client=client)
with mock.patch("google.cloud.firestore.async_transactional", lambda f: f):
session = await service.create_session(
app_name="app", user_id="u1", state={"due": datetime.date(2026, 11, 18)}
)
print("session state with a date: stored")
stored = mock.MagicMock(exists=True)
stored.to_dict.return_value = {"revision": 0}
ref.collection.return_value.document.return_value.get = mock.AsyncMock(return_value=stored)
try:
await service.append_event(
session,
Event(
author="agent",
actions=EventActions(state_delta={"user:due": datetime.date(2026, 11, 18)}),
),
)
print("user: state with a date: stored, events:", len(session.events))
except TypeError as e:
print("user: state with a date: append_event failed:", repr(e))
print("events:", len(session.events))
asyncio.run(main())How often has this issue occurred?:
- Always (100%), whenever
app:oruser:state holds such a value.
I have a fix with regression tests ready and will open a PR for it.
Activity
AliMuhammadAslam commentedon Nov 18, 2026
I've opened #8232 to resolve this issue.
Root cause
For
app:anduser:state,_encode_firestore_valueonly wraps nested lists and passes every other value to the Firestore client unchanged. Values the client can't encode raiseTypeErrorinside the write transaction. These includedatetime.date,uuid.UUID,decimal.Decimal, a plainEnumand Pydantic models. As a result,append_eventloses the event andcreate_sessionfails.Fix
None,bool,int,float,str,bytes,datetime,GeoPointand document references. Existing behaviour and stored data are not affected._session_util.make_json_safe_state. Session-level state already uses that conversion, and so do the Database, SQLite, Redis, MongoDB and Vertex AI session services.Testing
create_sessionandappend_event, covering a date, UUID, Decimal, Enum and Pydantic model. Each test passes the written state through the Firestore client's ownencode_dict/decode_dictand reads it back withget_user_state. They fail onmainwith theTypeErrorabove and pass with the fix.GeoPoint,bytes,datetime) are still stored unchanged.tests/unittests/sessionsandtests/unittests/integrations/firestore: 1246 passed.isort,pyinkandmypyare clean.I'd welcome being assigned to this issue and will follow up promptly on any review feedback.