langchain-ai/deepagents · error · DeepAgentsHomeError

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

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.

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

• Editor command resolved to no arguments
• Failed to parse as JSON: . Value was
• Home directory is not absolute
• Invalid DEEPAGENTS_HOME
• Invalid DEEPAGENTS_HOME

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

Appendix: 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)