{"record":{"id":"e5c40a4688c1fbfc","repo":"langchain-ai/deepagents","slug":"what-must-be-absolute-path","errorCode":null,"errorMessage":"{what} must be absolute: {path}","messagePattern":"(.+?) must be absolute: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":578,"sourceCode":"\n\ndef _normalize_absolute(path: Path, *, what: str = \"Path\") -> Path:\n    \"\"\"Normalize an already-absolute path without touching the filesystem.\n\n    Args:\n        path: Path to normalize.\n        what: Noun used in the error message, so a failure names the input that\n            was actually wrong.\n\n    Returns:\n        The lexically normalized absolute path.\n\n    Raises:\n        ValueError: If `path` is relative.\n    \"\"\"\n    if not path.is_absolute():\n        msg = f\"{what} must be absolute: {path}\"\n        raise ValueError(msg)\n    return Path(os.path.normpath(str(path)))\n\n\ndef _resolve_launch_home(launch_home: Path | None) -> Path:\n    \"\"\"Return the explicit or OS-resolved launch home as an absolute path.\n\n    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:","sourceCodeStart":560,"sourceCodeEnd":596,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L560-L596","documentation":"_normalize_absolute rejects relative paths for configuration values that must be absolute (home dir, profile root, installation paths). It raises ValueError when Path.is_absolute() is False, then returns the normalized absolute path. Callers wrap this for DEEPAGENTS_HOME-derived values and re-raise as DeepAgentsHomeError.","triggerScenarios":"Calling project_paths, _resolve_launch_home, _resolve_profile_root_unchecked, or _installation_paths with a relative path argument for the 'what' component being validated — e.g. passing DEEPAGENTS_HOME='deepagents-home' instead of '/abs/deepagents-home'.","commonSituations":"DEEPAGENTS_HOME set to a relative path in a shell profile; config file storing a path relative to the config's location; tests passing Path('relative/dir').","solutions":["Convert to absolute before calling: Path(value).resolve() or path.expanduser().resolve().","Set DEEPAGENTS_HOME to an absolute path (starting with / on POSIX, drive letter on Windows).","In config, anchor relative paths to a known base (home or project root) before passing them."],"exampleFix":"// before\nos.environ['DEEPAGENTS_HOME'] = 'deepagents-home'\n// after\nos.environ['DEEPAGENTS_HOME'] = str(Path('deepagents-home').resolve())","handlingStrategy":"validation","validationCode":"from pathlib import Path\ndef ensure_absolute(p: Path, what: str = 'Path') -> Path:\n    if not p.is_absolute():\n        raise ValueError(f'{what} must be absolute: {p}')\n    return p","typeGuard":"def is_absolute_path(p: Path) -> bool:\n    return isinstance(p, Path) and p.is_absolute()","tryCatchPattern":"try:\n    paths = project_paths(...)\nexcept ValueError as exc:\n    if 'must be absolute' in str(exc):\n        # re-anchor the value to an absolute base and retry\n        ...","preventionTips":["Always .resolve() paths read from config before passing them to the library.","Set DEEPAGENTS_HOME as an absolute path in shell profiles and .env files.","Add absolute-path assertions to integration test setup."],"tags":["validation","paths","configuration"],"backgroundTag":"relative-path-not-allowed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}