langchain-ai/deepagents · error · DeepAgentsHomeError

Home directory is not absolute: {launch_home}. Set $HOME to

Error message

Home directory is not absolute: {launch_home}. Set $HOME to an absolute path, or set DEEPAGENTS_HOME to an absolute profile path.

What it means

When an explicit launch home is supplied but is not an absolute path, _resolve_launch_home converts the ValueError from _normalize_absolute into DeepAgentsHomeError with actionable guidance. Relative home paths are rejected so the profile root never depends on the current working directory.

Source

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

    if launch_home is None:
        try:
            launch_home = Path.home()
        except RuntimeError as exc:
            # `Path.home()` raises when $HOME is unset and the uid has no passwd
            # entry: a bare container, or a cleared-environment service unit.
            msg = (
                "Could not determine the home directory: set $HOME, or set "
                "DEEPAGENTS_HOME to an absolute profile path."
            )
            raise DeepAgentsHomeError(msg) from exc
    try:
        return _normalize_absolute(launch_home, what="Home directory")
    except ValueError as exc:
        msg = (
            f"Home directory is not absolute: {launch_home}. Set $HOME to an "
            "absolute path, or set DEEPAGENTS_HOME to an absolute profile path."
        )
        raise DeepAgentsHomeError(msg) from exc


def _same_directory(left: Path, right: Path) -> bool:
    """Report whether two paths name the same directory.

    Path construction stays lexical on purpose, so `..` chains resolve without
    touching the filesystem. Identity is a different question: a lexical `==`
    misses a symlinked spelling of the target, and misses a case difference on
    the case-insensitive filesystems that are the default on macOS and Windows.
    Both are ordinary ways to spell the home directory, so both must compare
    equal here. `Path.samefile` compares device and inode. That settles every
    spelling at once. `os.path.normcase` does not, because it is a no-op on
    POSIX.

    A missing path is a real answer: it cannot be the directory it is compared
    against. Any other `OSError` is not an answer, and this function refuses to
    guess. Callers use it to reject a profile root, so a wrong `False` accepts
    the alias the caller meant to reject.

View on GitHub (pinned to a1af029e6e)

Solutions

Make DEEPAGENTS_HOME absolute: export DEEPAGENTS_HOME="$HOME/.deepagents".
In code, resolve before passing: Path(value).expanduser().resolve().
Fix .env files that use relative values; .env does not perform shell expansion.

Example fix

// before (.env)
DEEPAGENTS_HOME=.deepagents
// after
DEEPAGENTS_HOME=/home/dev/.deepagents

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
import os
raw = os.environ.get('DEEPAGENTS_HOME', '')
if raw and not Path(raw).is_absolute():
    os.environ['DEEPAGENTS_HOME'] = str(Path(raw).expanduser().resolve())

Type guard

def is_absolute_str(p: str) -> bool:
    return Path(p).is_absolute()

Try / catch

try:
    root = _resolve_profile_root()
except DeepAgentsHomeError as exc:
    if 'not absolute' in str(exc):
        os.environ['DEEPAGENTS_HOME'] = str(Path(os.environ['DEEPAGENTS_HOME']).resolve())
        root = _resolve_profile_root()
    else:
        raise

Prevention

Use $HOME expansion in shell exports; remember .env files do not expand variables.
Normalize with Path(value).expanduser().resolve() at config load time.
Validate DEEPAGENTS_HOME in startup scripts before launching the app.

When it happens

Trigger: Setting DEEPAGENTS_HOME to a relative path like 'deepagents-home' or './profile', then importing/initializing the library; passing a relative Path as launch_home.

Common situations: DEEPAGENTS_HOME='.deepagents' written in a .env file; docs or scripts assuming the path is resolved against cwd; dotfiles that export DEEPAGENTS_HOME=$HOME/.deepagents without quoting/expansion.

Related errors

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