[Bug]: Potential sqlite3.OperationalError database is locked during highly concurrent aput operations

[Jacopos311]

Checked other resources

• This is a bug, not a usage question.
• I added a clear and descriptive title that summarizes this issue.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangGraph rather than my code.
• The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package).
• This is not related to the langchain-community package.
• I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.

Related Issues / PRs

None

Reproduction Steps / Example Code (Python)

import asyncio
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.base import Checkpoint, CheckpointMetadata
from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver

async def simulate_concurrent_writes():
    # Initialize the checkpointer in memory
    async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
        await saver.setup()
        
        # Prepare mock checkpoint data
        config: RunnableConfig = {"configurable": {"thread_id": "test_thread", "checkpoint_ns": ""}}
        checkpoint: Checkpoint = {"v": 1, "id": "1", "ts": "2026-01-01T00:00:00Z", "channel_values": {}, "channel_versions": {}, "versions_seen": {}}
        metadata: CheckpointMetadata = {"source": "input", "step": 1, "writes": {}}
        new_versions = {}

        # Worker simulating concurrent agent writes
        async def worker(worker_id):
            cfg = config.copy()
            cfg["configurable"] = config["configurable"].copy()
            cfg["configurable"]["checkpoint_id"] = f"check_{worker_id}"
            await saver.aput(cfg, checkpoint, metadata, new_versions)

        # Trigger 50 concurrent writes at the exact same time
        # Without BEGIN IMMEDIATE, this highly concurrent scenario can expose
        # the database to "sqlite3.OperationalError: database is locked"
        tasks = [worker(i) for i in range(50)]
        await asyncio.gather(*tasks)

if __name__ == "__main__":
    asyncio.run(simulate_concurrent_writes())

Error Message and Stack Trace (if applicable)

Description

Description

In high-concurrency environments, when multiple async agents attempt to write checkpoints simultaneously using AsyncSqliteSaver.aput, SQLite can occasionally fail with a sqlite3.OperationalError: database is locked.

Proposed Fix

Enforcing a BEGIN IMMEDIATE transaction block within the async with self.lock section inside langgraph/checkpoint/sqlite/aio.py ensures that SQLite acquires a write lock before executing the statement, preventing concurrent write collisions.

System Info

System Information

OS: Windows
OS Version: 10.0.26200
Python Version: 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)]

Package Information

langchain_core: 1.4.7
langsmith: 0.8.16
langchain_protocol: 0.0.17

Optional packages not installed

deepagents
deepagents-cli

Other Dependencies

httpx: 0.28.1
jsonpatch: 1.33
orjson: 3.11.9
packaging: 26.2
pydantic: 2.13.4
pyyaml: 6.0.3
requests: 2.32.3
requests-toolbelt: 1.0.0
rich: 15.0.0
tenacity: 9.1.4
typing-extensions: 4.15.0
uuid-utils: 0.16.2
websockets: 15.0
wrapt: 2.2.1
xxhash: 3.7.0
zstandard: 0.25.0

[Jacopos311]

Please assign this issue to me. I have already opened a Pull Request with the fix.

[hiSandog]

For this class of failure, it would be useful for the regression test to cover both the SQLite busy timeout and the async write fan-out. If the fix serializes aput operations on a single connection, the test should still run many concurrent tasks so it proves callers can keep the same public concurrency pattern without surfacing database is locked. It may also be worth documenting whether the SQLite saver is intended for highly concurrent production use or only local/dev checkpointing.

[ly-wang19]

Took a look at the source — I think the issue's repro and the proposed BEGIN IMMEDIATE fix don't quite line up, and there's a smaller intervention that's more likely to address the production failure mode.

The asyncio.Lock already serializes within one saver. aput (libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py:537) and aput_writes (line 584) both wrap the execute + commit in async with self.lock:. The setup at line 312 also holds the lock. The 50-worker repro uses a single AsyncSqliteSaver instance with :memory:, which means all 50 coroutines funnel through one asyncio.Lock and one underlying aiosqlite connection — the workers cannot execute concurrently at the SQLite level. If you can actually reproduce database is locked with the snippet as written, that's a different bug class (e.g., aiosqlite queuing the next statement on its worker thread before the previous commit resolves) and worth a stack trace.

The real failure mode is cross-connection, not within-saver. "database is locked" from SQLite is raised when a different OS-level connection holds the write lock. That happens when:

• Multiple AsyncSqliteSaver instances open the same on-disk file (e.g., one per process, or two savers in one process),
• Or SqliteSaver (sync) and AsyncSqliteSaver are pointed at the same file.

PRAGMA journal_mode=WAL (line 318) helps — readers don't block writers and vice-versa — but writers still serialize, and busy_timeout defaults to 0, so the first contended write raises immediately instead of waiting. There's no busy_timeout set anywhere in checkpoint-sqlite today.

Proposed fix (smallest correct shape):

# libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py:318, inside setup()
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;   -- 5s: retry on SQLITE_BUSY before raising

This is the SQLite-recommended knob for exactly this symptom. Five seconds is a common default (matches e.g. aiosqlite's own docs); the value is configurable if a maintainer wants it tunable. The same PRAGMA should land in the sync SqliteSaver.setup for parity.

Why not BEGIN IMMEDIATE:

• The current code uses self.conn.execute(...) + await self.conn.commit() and relies on the DB-API implicit transaction. There's no explicit BEGIN anywhere in aio.py. Switching to BEGIN IMMEDIATE requires restructuring every aput/aput_writes/adelete_thread into explicit-transaction form (you can't executescript a BEGIN in py3 sqlite3, and you can't BEGIN while inside an open transaction — it gets fiddly).
• BEGIN IMMEDIATE acquires the write lock at BEGIN time, which serializes the whole transaction including any read preamble. For the single-connection saver that's strictly worse than what the asyncio.Lock already does.
• busy_timeout addresses the actual cross-connection case without restructuring transaction handling.

Test plan I'd include in a PR:

1. Open two AsyncSqliteSaver instances against the same on-disk temp file.
2. Fire N concurrent aput calls across both savers.
3. Without the fix: surface OperationalError: database is locked reliably within a few iterations.
4. With busy_timeout=5000: same scenario completes cleanly.

I cannot reproduce the bug with the issue's single-saver :memory: snippet, so a maintainer should confirm whether multi-connection contention is the intended target before merging — but busy_timeout is cheap and correct to set regardless of that answer, since it has no downside for the within-saver case.

Happy to open the PR if this shape looks right.

[Jacopos311]

Test Coverage & Documentation Considerations

To ensure this is robust moving forward, the regression test should ideally cover two main aspects:

1. The Multi-Connection Race: As outlined above, testing with multiple separate saver instances hitting the same file to ensure busy_timeout handles the contention cleanly.
2. The Async Fan-Out (Public API Safety): Even though the internal asyncio.Lock serializes execution within a single connection, the test should still fire a massive fan-out of concurrent tasks (just like the original reproduction snippet). This guarantees that from the caller's perspective, the public concurrency pattern remains completely safe and doesn't leak any underlying database is locked operational errors.

Note on Scope & Documentation

Given that SQLite is generally optimized for local development or lightweight single-process applications, it might also be worth adding a small note to the LangGraph documentation. Clarifying whether SqliteSaver / AsyncSqliteSaver are officially intended for highly concurrent, multi-process production environments—or if production workloads with high concurrency should strictly point towards more robust production checkpointers (like Postgres)—would be incredibly helpful for architectural decisions.

Let me know if this comprehensive approach makes sense, and I can include both the fix and the updated test suite in the PR!