{"record":{"id":"c568629c4a5971dc","repo":"langchain-ai/deepagents","slug":"not-a-supported-sessions-database-missing-tables","errorCode":null,"errorMessage":"Not a supported sessions database; missing tables: {names}","messagePattern":"Not a supported sessions database; missing tables: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py","lineNumber":160,"sourceCode":"def _connect_read_only(path: Path) -> sqlite3.Connection:\n    resolved = path.expanduser().resolve()\n    if not resolved.is_file():\n        msg = f\"Sessions database not found: {resolved}\"\n        raise SystemExit(msg)\n    conn = sqlite3.connect(f\"{resolved.as_uri()}?mode=ro\", uri=True)\n    conn.row_factory = sqlite3.Row\n    tables = {\n        row[0]\n        for row in conn.execute(\n            \"SELECT name FROM sqlite_master WHERE type = 'table'\"\n        ).fetchall()\n    }\n    missing = {\"checkpoints\", \"writes\"} - tables\n    if missing:\n        conn.close()\n        names = \", \".join(sorted(missing))\n        msg = f\"Not a supported sessions database; missing tables: {names}\"\n        raise SystemExit(msg)\n    return conn\n\n\ndef _resolve_thread_id(conn: sqlite3.Connection, value: str) -> str:\n    exact = conn.execute(\n        \"SELECT 1 FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = '' LIMIT 1\",\n        (value,),\n    ).fetchone()\n    if exact:\n        return value\n    escaped = value.replace(\"\\\\\", \"\\\\\\\\\").replace(\"%\", \"\\\\%\").replace(\"_\", \"\\\\_\")\n    rows = conn.execute(\n        \"SELECT DISTINCT thread_id FROM checkpoints \"\n        \"WHERE checkpoint_ns = '' AND thread_id LIKE ? ESCAPE '\\\\' \"\n        \"ORDER BY thread_id LIMIT 11\",\n        (escaped + \"%\",),\n    ).fetchall()\n    matches = [str(row[0]) for row in rows]","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py#L142-L178","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Point `--db` at the real sessions DB (default `~/.deepagents/.state/sessions.db`) rather than another SQLite file.","Confirm the file is a dcode sessions DB: `sqlite3 <file> '.tables'` should list `checkpoints` and `writes`.","If the DB is truncated/corrupt, restore it from backup or re-run the sessions in dcode to regenerate it.","Check the dcode version: a very old/new schema may differ — align the inspector with the version that wrote the DB."],"exampleFix":"// before\n$ python inspect_sessions.py --db ./cache.db  # foreign SQLite file\n// after\n$ python inspect_sessions.py --db ~/.deepagents/.state/sessions.db","handlingStrategy":"validation","validationCode":"import sqlite3\ndef is_sessions_db(path) -> bool:\n    conn = sqlite3.connect(f\"file:{path}?mode=ro\", uri=True)\n    try:\n        tables = {r[0] for r in conn.execute(\"SELECT name FROM sqlite_master WHERE type='table'\")}\n    finally:\n        conn.close()\n    return {'checkpoints', 'writes'} <= tables","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `sqlite3 <file> '.tables'` and confirm `checkpoints` and `writes` exist before pointing --db at a file.","Only pass dcode-generated sessions DB files, not arbitrary SQLite files.","Verify DB integrity after interrupted runs; regenerate by rerunning dcode if corrupt.","Align inspector and dcode versions so the expected schema matches."],"tags":["sqlite","schema-validation","script","file-not-found"],"backgroundTag":"database-schema-mismatch","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}