{"record":{"id":"338f1ba399b5c82c","repo":"langchain-ai/deepagents","slug":"home-directory-is-not-absolute-launch-home-set","errorCode":null,"errorMessage":"Home directory is not absolute: {launch_home}. Set $HOME to an absolute path, or set DEEPAGENTS_HOME to an absolute profile path.","messagePattern":"Home directory is not absolute: (.+?)\\. Set \\$HOME to an absolute path, 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":611,"sourceCode":"    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\n    equal here. `Path.samefile` compares device and inode. That settles every\n    spelling at once. `os.path.normcase` does not, because it is a no-op on\n    POSIX.\n\n    A missing path is a real answer: it cannot be the directory it is compared\n    against. Any other `OSError` is not an answer, and this function refuses to\n    guess. Callers use it to reject a profile root, so a wrong `False` accepts\n    the alias the caller meant to reject.","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L593-L629","documentation":"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.","triggerScenarios":"Setting DEEPAGENTS_HOME to a relative path like 'deepagents-home' or './profile', then importing/initializing the library; passing a relative Path as launch_home.","commonSituations":"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.","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."],"exampleFix":"// before (.env)\nDEEPAGENTS_HOME=.deepagents\n// after\nDEEPAGENTS_HOME=/home/dev/.deepagents","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport os\nraw = os.environ.get('DEEPAGENTS_HOME', '')\nif raw and not Path(raw).is_absolute():\n    os.environ['DEEPAGENTS_HOME'] = str(Path(raw).expanduser().resolve())","typeGuard":"def is_absolute_str(p: str) -> bool:\n    return Path(p).is_absolute()","tryCatchPattern":"try:\n    root = _resolve_profile_root()\nexcept DeepAgentsHomeError as exc:\n    if 'not absolute' in str(exc):\n        os.environ['DEEPAGENTS_HOME'] = str(Path(os.environ['DEEPAGENTS_HOME']).resolve())\n        root = _resolve_profile_root()\n    else:\n        raise","preventionTips":["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."],"tags":["environment","paths","configuration","validation"],"backgroundTag":"relative-path-not-allowed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}