langchain-ai/deepagents · error · SystemExit

Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path

Error message

Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path or a path beginning with '~/'.

What it means

The thread-inspector resolves the sessions database location from the `DEEPAGENTS_HOME` environment variable; the value must be an absolute path or start with `~/`. `_default_db_path` (called while building the CLI parser) raises SystemExit with this message for any relative path or bare `~` form it cannot expand, because such values would resolve to an unpredictable directory.

Source

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

        return Path(explicit).expanduser()
    try:
        from deepagents_code._paths import get_deepagents_home  # noqa: PLC2701
    except ImportError:
        # Standalone fallback. It must apply the same rules as
        # `_paths._resolve_profile_root`: relative paths and `~user` forms are
        # rejected rather than coerced, because a lenient reading here would
        # silently inspect a different profile than the app uses.
        configured = os.environ.get("DEEPAGENTS_HOME")
        if not configured:
            home = Path.home() / ".deepagents"
        elif configured.startswith("~/"):
            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'"

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set `DEEPAGENTS_HOME` to an absolute path: `export DEEPAGENTS_HOME=/home/user/.deepagents`.
2. Use the tilde form correctly: `export DEEPAGENTS_HOME=~/.deepagents` (must start with `~/`).
3. Unset `DEEPAGENTS_HOME` to fall back to `get_deepagents_home()` defaults.
4. Fix your shell profile so the variable is expanded at export time (use `$HOME` or quote correctly).

Example fix

// before
export DEEPAGENTS_HOME=.deepagents   # relative path -> SystemExit
// after
export DEEPAGENTS_HOME="$HOME/.deepagents"

import os
configured = os.environ.get('DEEPAGENTS_HOME')
if configured and (configured.startswith('~') and not configured.startswith('~/') or not configured.startswith('~') and not os.path.isabs(configured)):
    del os.environ['DEEPAGENTS_HOME']  # fall back to default instead of SystemExit

def deepagents_home_is_valid(configured: str) -> bool:
    return configured.startswith('~/') or os.path.isabs(configured)

When it happens

Trigger: Exporting `DEEPAGENTS_HOME` to a relative path like `DEEPAGENTS_HOME=data` or a malformed tilde form like `DEEPAGENTS_HOME=~x/y` (tilde not followed by `/`), then running inspect_sessions.py.

Common situations: Shell config exporting DEEPAGENTS_HOME without `$HOME` expansion (unquoted `~` in some contexts); typos like a leading dot-relative path; copying a config from another tool expecting relative homes.

Related errors

• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path
• Could not determine the home directory: set $HOME, or set DE
• Home directory is not absolute: {launch_home}. Set $HOME to
• Repository root must be an absolute contained path: {root!r}
• Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}.

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