langchain-ai/deepagents · error · DeepAgentsHomeError

Could not determine the home directory: set $HOME, or set DE

Error message

Could not determine the home directory: set $HOME, or set DEEPAGENTS_HOME to an absolute profile path.

What it means

_resolve_launch_home raises DeepAgentsHomeError when it cannot determine the user's home directory: Path.home() failed (typically $HOME unset and no passwd entry for the uid) and no explicit DEEPAGENTS_HOME absolute profile path was supplied. The library needs a home to anchor the profile root and cannot guess.

Source

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

    Returns:
        The normalized launch home.

    Raises:
        DeepAgentsHomeError: If the home directory cannot be determined or is
            not absolute. Both are reported against `DEEPAGENTS_HOME` because
            setting it to an absolute path is the way out of either.
    """
    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

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set DEEPAGENTS_HOME to an absolute profile path in the environment.
2. Set HOME explicitly (e.g. HOME=/root or HOME=/home/appuser) in the container/unit file.
3. Ensure the runtime uid has a passwd entry (add it in the Dockerfile) so Path.home() works.

Example fix

// before (docker)
USER 10001
// after
ENV HOME=/home/app \
    DEEPAGENTS_HOME=/home/app/.deepagents
USER 10001

import os
from pathlib import Path
if 'HOME' not in os.environ and 'DEEPAGENTS_HOME' not in os.environ:
    os.environ['DEEPAGENTS_HOME'] = str(Path.cwd() / '.deepagents-home')

try:
    root = _resolve_profile_root()
except DeepAgentsHomeError:
    os.environ.setdefault('DEEPAGENTS_HOME', '/tmp/app-home/.deepagents')
    root = _resolve_profile_root()

When it happens

Trigger: Running in a bare container or cleared-environment systemd service where $HOME is unset, the uid has no /etc/passwd entry, and DEEPAGENTS_HOME is not set.

Common situations: Docker containers run with a numeric uid and 'env -i'; systemd units with a sanitized environment; CI runners stripping HOME; schedulers (cron/k8s) with minimal env.

Related errors

• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path
• Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}.
• Invalid {SERVER_ENV_PREFIX}{suffix}: expected a JSON string
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path

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