langchain-ai/deepagents · error · SystemExit

Sessions database not found: {resolved}

Error message

Sessions database not found: {resolved}

What it means

Before querying, `_connect_read_only` resolves the sessions DB path (expanduser + resolve) and verifies it exists as a regular file; if not, the script exits with this SystemExit message showing the resolved path. This means there is no sessions database at the expected location — the inspector cannot open anything in read-only SQLite mode.

Source

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

            home = Path.home() / configured[2:].lstrip("/")
        elif configured.startswith("~") or not Path(configured).is_absolute():
            msg = (
                f"Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path "
                "or a path beginning with '~/'."
            )
            raise SystemExit(msg) from None
        else:
            home = Path(configured)
    else:
        home = get_deepagents_home()
    return home / ".state" / "sessions.db"


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:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Verify the resolved path in the message exists (`ls <resolved>`); if not, locate the real DB (default `~/.deepagents/.state/sessions.db`).
2. Set `DEEPAGENTS_HOME` to the directory that actually contains `.state/sessions.db`, or pass `--db /path/to/sessions.db`.
3. Run dcode at least once to create the database before inspecting.
4. Check you are on the machine/user account where the sessions were recorded.

Example fix

// before
$ python inspect_sessions.py --db ./old/sessions.db  # file absent
// after
$ python inspect_sessions.py --db ~/.deepagents/.state/sessions.db

from pathlib import Path
from deepagents_code.paths import get_deepagents_home
# or derive manually
db = Path(os.environ.get('DEEPAGENTS_HOME', str(Path.home() / '.deepagents'))) / '.state' / 'sessions.db'
if not db.expanduser().is_file():
    raise SystemExit(f'no sessions db at {db}; run dcode first or pass --db')

def sessions_db_exists(path) -> bool:
    return path.expanduser().resolve().is_file()

When it happens

Trigger: Running inspect_sessions.py with `--db` pointing to a non-existent file, or with the default path derived from `DEEPAGENTS_HOME`/`get_deepagents_home()` where no session has ever been recorded (missing `~/.deepagents/.state/sessions.db`).

Common situations: Wrong `DEEPAGENTS_HOME` pointing at a fresh/empty directory; inspecting sessions from a different machine or user; typo in `--db`; running before ever launching dcode so no DB was created.

Related errors

• Not a supported sessions database; missing tables: {names}
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path
• {what} must be absolute: {path}
• Could not determine the home directory: set $HOME, or set DE
• Home directory is not absolute: {launch_home}. Set $HOME to

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