{"record":{"id":"6ef40db6dab348c3","repo":"langchain-ai/deepagents","slug":"invalid-deepagents-home-configured-r-use-an-abs","errorCode":null,"errorMessage":"Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path or a path beginning with '~'.","messagePattern":"Invalid DEEPAGENTS_HOME (.+?): use an absolute path or a path beginning with '~'\\.","errorType":"exception","errorClass":"DeepAgentsHomeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":822,"sourceCode":"        return home / DEFAULT_PROFILE_DIR_NAME, True, home\n    if configured.startswith(\"~/\"):\n        home = _resolve_launch_home(launch_home)\n        relative = configured[2:].lstrip(\"/\")\n        return _normalize_absolute(home / relative), False, home\n    if configured.startswith(\"~\"):\n        msg = (\n            \"Invalid DEEPAGENTS_HOME: only an absolute path or a leading '~/' \"\n            \"path is supported; '~user' forms are not allowed.\"\n        )\n        raise DeepAgentsHomeError(msg)\n\n    path = Path(configured)\n    if not path.is_absolute():\n        msg = (\n            f\"Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path or \"\n            \"a path beginning with '~/'.\"\n        )\n        raise DeepAgentsHomeError(msg)\n    # An absolute profile does not need a home directory; only report a home\n    # that was handed to us explicitly.\n    home = _normalize_absolute(launch_home) if launch_home is not None else None\n    return _normalize_absolute(path), False, home\n\n\ndef _profile_paths(root: Path) -> ProfilePaths:\n    \"\"\"Build the profile-owned portion of the immutable snapshot.\n\n    Returns:\n        All paths owned by the selected user profile.\n    \"\"\"\n    state_dir = root / \".state\"\n    return ProfilePaths(\n        root=root,\n        config_file=root / \"config.toml\",\n        dotenv_file=root / \".env\",\n        mcp_config_file=root / \".mcp.json\",","sourceCodeStart":804,"sourceCodeEnd":840,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L804-L840","documentation":"This error is raised by `_resolve_profile_root_unchecked` in `libs/code/deepagents_code/_paths.py` when the `DEEPAGENTS_HOME` environment variable (or equivalent configured value) is a relative path. The library requires the home/profile root to be either an absolute path or a path starting with `~/` so profile state (config, sessions, history) resolves to a deterministic location independent of the current working directory. A relative value is ambiguous and could silently create different profile roots depending on where the process is launched, so it is rejected up front with `DeepAgentsHomeError`.","triggerScenarios":"Setting `DEEPAGENTS_HOME` to a relative value such as `mydir`, `./dcode-home`, `deepagents` (no leading `/` or `~/`), or an empty-with-text fragment before any process launches its profile. Also triggered when a launcher script or shell profile exports `DEEPAGENTS_HOME=\"$PWD/something\"` after an earlier `cd`, or passes a relative path programmatically to the profile-root resolution that wraps `_resolve_profile_root_unchecked`.","commonSituations":"Developers setting `DEEPAGENTS_HOME=.dcode` in a dotfile intending a per-project profile; CI scripts exporting a relative path before `cd`ing into the workspace; dotfile managers expanding `~` manually into `~user` or a bare tilde variant (which hits sibling errors); users copying a Docker `WORKDIR`-relative path into the variable.","solutions":["Set `DEEPAGENTS_HOME` to an absolute path, e.g. `export DEEPAGENTS_HOME=/home/alice/.dcode`.","Use the supported tilde form, e.g. `export DEEPAGENTS_HOME='~/.dcode'` (must be exactly a leading `~/`, quoted so the shell does not expand it if you want the library to resolve it).","In scripts, prefix with `$PWD` or `${HOME}` to absolutize: `export DEEPAGENTS_HOME=\"$PWD/.dcode\"` only if an absolute expansion is guaranteed.","Unset `DEEPAGENTS_HOME` entirely to fall back to the default profile location under the launch home."],"exampleFix":"// before (shell)\nexport DEEPAGENTS_HOME=.dcode\n// after (shell)\nexport DEEPAGENTS_HOME=\"$HOME/.dcode\"","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\ndef valid_deepagents_home() -> bool:\n    configured = os.environ.get(\"DEEPAGENTS_HOME\")\n    if not configured:\n        return True  # falls back to default\n    return configured.startswith(\"~/\") or Path(configured).is_absolute()","typeGuard":"def is_supported_home(value: str) -> bool:\n    return value.startswith(\"~/\") or Path(value).is_absolute()","tryCatchPattern":"try:\n    launch()\nexcept DeepAgentsHomeError as exc:\n    print(f\"Fix DEEPAGENTS_HOME: {exc}\")\n    os.environ[\"DEEPAGENTS_HOME\"] = str(Path.home() / \".dcode\")","preventionTips":["Always define DEEPAGENTS_HOME with $HOME or an absolute path in shell profiles.","Quote '~/' values so the shell does not expand or mangle them.","Avoid '~user' and bare '~' forms; they are separately rejected.","Add a startup validation step in launch scripts before spawning the process."],"tags":["configuration","environment","path-validation"],"backgroundTag":"invalid-home-path","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}