langchain-ai/deepagents · error · DeepAgentsHomeError

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

This error is raised by `_resolve_profile_root_unchecked` in `libs/code/deepagents_code/_paths.py` when the `DEEPAGENTS_HOME` environment variable (or equivalent configured value) is a relative path. The library requires the home/profile root to be either an absolute path or a path starting with `~/` so profile state (config, sessions, history) resolves to a deterministic location independent of the current working directory. A relative value is ambiguous and could silently create different profile roots depending on where the process is launched, so it is rejected up front with `DeepAgentsHomeError`.

Source

Thrown at libs/code/deepagents_code/_paths.py:822

        return home / DEFAULT_PROFILE_DIR_NAME, True, home
    if configured.startswith("~/"):
        home = _resolve_launch_home(launch_home)
        relative = configured[2:].lstrip("/")
        return _normalize_absolute(home / relative), False, home
    if configured.startswith("~"):
        msg = (
            "Invalid DEEPAGENTS_HOME: only an absolute path or a leading '~/' "
            "path is supported; '~user' forms are not allowed."
        )
        raise DeepAgentsHomeError(msg)

    path = Path(configured)
    if not path.is_absolute():
        msg = (
            f"Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path or "
            "a path beginning with '~/'."
        )
        raise DeepAgentsHomeError(msg)
    # An absolute profile does not need a home directory; only report a home
    # that was handed to us explicitly.
    home = _normalize_absolute(launch_home) if launch_home is not None else None
    return _normalize_absolute(path), False, home


def _profile_paths(root: Path) -> ProfilePaths:
    """Build the profile-owned portion of the immutable snapshot.

    Returns:
        All paths owned by the selected user profile.
    """
    state_dir = root / ".state"
    return ProfilePaths(
        root=root,
        config_file=root / "config.toml",
        dotenv_file=root / ".env",
        mcp_config_file=root / ".mcp.json",

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set `DEEPAGENTS_HOME` to an absolute path, e.g. `export DEEPAGENTS_HOME=/home/alice/.dcode`.
2. Use the supported tilde form, e.g. `export DEEPAGENTS_HOME='~/.dcode'` (must be exactly a leading `~/`, quoted so the shell does not expand it if you want the library to resolve it).
3. In scripts, prefix with `$PWD` or `${HOME}` to absolutize: `export DEEPAGENTS_HOME="$PWD/.dcode"` only if an absolute expansion is guaranteed.
4. Unset `DEEPAGENTS_HOME` entirely to fall back to the default profile location under the launch home.

Example fix

// before (shell)
export DEEPAGENTS_HOME=.dcode
// after (shell)
export DEEPAGENTS_HOME="$HOME/.dcode"

import os
from pathlib import Path

def valid_deepagents_home() -> bool:
    configured = os.environ.get("DEEPAGENTS_HOME")
    if not configured:
        return True  # falls back to default
    return configured.startswith("~/") or Path(configured).is_absolute()

def is_supported_home(value: str) -> bool:
    return value.startswith("~/") or Path(value).is_absolute()

try:
    launch()
except DeepAgentsHomeError as exc:
    print(f"Fix DEEPAGENTS_HOME: {exc}")
    os.environ["DEEPAGENTS_HOME"] = str(Path.home() / ".dcode")

When it happens

Trigger: Setting `DEEPAGENTS_HOME` to a relative value such as `mydir`, `./dcode-home`, `deepagents` (no leading `/` or `~/`), or an empty-with-text fragment before any process launches its profile. Also triggered when a launcher script or shell profile exports `DEEPAGENTS_HOME="$PWD/something"` after an earlier `cd`, or passes a relative path programmatically to the profile-root resolution that wraps `_resolve_profile_root_unchecked`.

Common situations: Developers setting `DEEPAGENTS_HOME=.dcode` in a dotfile intending a per-project profile; CI scripts exporting a relative path before `cd`ing into the workspace; dotfile managers expanding `~` manually into `~user` or a bare tilde variant (which hits sibling errors); users copying a Docker `WORKDIR`-relative path into the variable.

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/6ef40db6dab348c3. Report an issue: GitHub.