{"record":{"id":"ce079d212189ad0b","repo":"langchain-ai/deepagents","slug":"could-not-determine-the-home-directory-set-home","errorCode":null,"errorMessage":"Could not determine the home directory: set $HOME, or set DEEPAGENTS_HOME to an absolute profile path.","messagePattern":"Could not determine the home directory: set \\$HOME, or set DEEPAGENTS_HOME to an absolute profile path\\.","errorType":"exception","errorClass":"DeepAgentsHomeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":603,"sourceCode":"    Returns:\n        The normalized launch home.\n\n    Raises:\n        DeepAgentsHomeError: If the home directory cannot be determined or is\n            not absolute. Both are reported against `DEEPAGENTS_HOME` because\n            setting it to an absolute path is the way out of either.\n    \"\"\"\n    if launch_home is None:\n        try:\n            launch_home = Path.home()\n        except RuntimeError as exc:\n            # `Path.home()` raises when $HOME is unset and the uid has no passwd\n            # entry: a bare container, or a cleared-environment service unit.\n            msg = (\n                \"Could not determine the home directory: set $HOME, or set \"\n                \"DEEPAGENTS_HOME to an absolute profile path.\"\n            )\n            raise DeepAgentsHomeError(msg) from exc\n    try:\n        return _normalize_absolute(launch_home, what=\"Home directory\")\n    except ValueError as exc:\n        msg = (\n            f\"Home directory is not absolute: {launch_home}. Set $HOME to an \"\n            \"absolute path, or set DEEPAGENTS_HOME to an absolute profile path.\"\n        )\n        raise DeepAgentsHomeError(msg) from exc\n\n\ndef _same_directory(left: Path, right: Path) -> bool:\n    \"\"\"Report whether two paths name the same directory.\n\n    Path construction stays lexical on purpose, so `..` chains resolve without\n    touching the filesystem. Identity is a different question: a lexical `==`\n    misses a symlinked spelling of the target, and misses a case difference on\n    the case-insensitive filesystems that are the default on macOS and Windows.\n    Both are ordinary ways to spell the home directory, so both must compare","sourceCodeStart":585,"sourceCodeEnd":621,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L585-L621","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set DEEPAGENTS_HOME to an absolute profile path in the environment.","Set HOME explicitly (e.g. HOME=/root or HOME=/home/appuser) in the container/unit file.","Ensure the runtime uid has a passwd entry (add it in the Dockerfile) so Path.home() works."],"exampleFix":"// before (docker)\nUSER 10001\n// after\nENV HOME=/home/app \\\n    DEEPAGENTS_HOME=/home/app/.deepagents\nUSER 10001","handlingStrategy":"fallback","validationCode":"import os\nfrom pathlib import Path\nif 'HOME' not in os.environ and 'DEEPAGENTS_HOME' not in os.environ:\n    os.environ['DEEPAGENTS_HOME'] = str(Path.cwd() / '.deepagents-home')","typeGuard":null,"tryCatchPattern":"try:\n    root = _resolve_profile_root()\nexcept DeepAgentsHomeError:\n    os.environ.setdefault('DEEPAGENTS_HOME', '/tmp/app-home/.deepagents')\n    root = _resolve_profile_root()","preventionTips":["Set HOME explicitly in Dockerfiles, systemd units, and CI containers.","Export DEEPAGENTS_HOME in entrypoint scripts for headless environments.","Ensure runtime uids have passwd entries in minimal images."],"tags":["environment","home-directory","containers","configuration"],"backgroundTag":"missing-home-directory","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}