langchain-ai/deepagents · error · SystemExit

Not a supported sessions database; missing tables: {names}

Error message

Not a supported sessions database; missing tables: {names}

What it means

After opening the SQLite file read-only, `_connect_read_only` inspects `sqlite_master` and requires the `checkpoints` and `writes` tables; if either is missing it closes the connection and exits with this message naming the missing tables. The file exists but is not a LangGraph-style sessions database the inspector can read — likely a corrupt, empty, or foreign SQLite file.

Source

Thrown at libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py:160

def _connect_read_only(path: Path) -> sqlite3.Connection:
    resolved = path.expanduser().resolve()
    if not resolved.is_file():
        msg = f"Sessions database not found: {resolved}"
        raise SystemExit(msg)
    conn = sqlite3.connect(f"{resolved.as_uri()}?mode=ro", uri=True)
    conn.row_factory = sqlite3.Row
    tables = {
        row[0]
        for row in conn.execute(
            "SELECT name FROM sqlite_master WHERE type = 'table'"
        ).fetchall()
    }
    missing = {"checkpoints", "writes"} - tables
    if missing:
        conn.close()
        names = ", ".join(sorted(missing))
        msg = f"Not a supported sessions database; missing tables: {names}"
        raise SystemExit(msg)
    return conn


def _resolve_thread_id(conn: sqlite3.Connection, value: str) -> str:
    exact = conn.execute(
        "SELECT 1 FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = '' LIMIT 1",
        (value,),
    ).fetchone()
    if exact:
        return value
    escaped = value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
    rows = conn.execute(
        "SELECT DISTINCT thread_id FROM checkpoints "
        "WHERE checkpoint_ns = '' AND thread_id LIKE ? ESCAPE '\\' "
        "ORDER BY thread_id LIMIT 11",
        (escaped + "%",),
    ).fetchall()
    matches = [str(row[0]) for row in rows]

View on GitHub (pinned to a1af029e6e)

Solutions

1. Point `--db` at the real sessions DB (default `~/.deepagents/.state/sessions.db`) rather than another SQLite file.
2. Confirm the file is a dcode sessions DB: `sqlite3 <file> '.tables'` should list `checkpoints` and `writes`.
3. If the DB is truncated/corrupt, restore it from backup or re-run the sessions in dcode to regenerate it.
4. Check the dcode version: a very old/new schema may differ — align the inspector with the version that wrote the DB.

Example fix

// before
$ python inspect_sessions.py --db ./cache.db  # foreign SQLite file
// after
$ python inspect_sessions.py --db ~/.deepagents/.state/sessions.db

import sqlite3
def is_sessions_db(path) -> bool:
    conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
    try:
        tables = {r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
    finally:
        conn.close()
    return {'checkpoints', 'writes'} <= tables

When it happens

Trigger: Pointing `--db` (or DEEPAGENTS_HOME) at a SQLite file that was never written by dcode — e.g. an empty file, another application's DB, or a truncated/incomplete download — so `checkpoints` and/or `writes` tables are absent.

Common situations: Passing the wrong file (e.g. a config or cache SQLite DB) via `--db`; an interrupted first run of dcode that created an empty DB file; inspecting a DB from a much older/newer schema version.

Related errors

• Sessions database not found: {resolved}
• Error: Source agent '{source_agent}' not found or has no AGE
• The selected Python runtime does not contain Deep Agents Cod
• Could not import Deep Agents Code dependencies or locate dco
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/c568629c4a5971dc. Report an issue: GitHub.