langchain-ai/deepagents · error · ValueError

{what} must be absolute: {path}

Error message

{what} must be absolute: {path}

What it means

_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.

Source

Thrown at libs/code/deepagents_code/_paths.py:578

def _normalize_absolute(path: Path, *, what: str = "Path") -> Path:
    """Normalize an already-absolute path without touching the filesystem.

    Args:
        path: Path to normalize.
        what: Noun used in the error message, so a failure names the input that
            was actually wrong.

    Returns:
        The lexically normalized absolute path.

    Raises:
        ValueError: If `path` is relative.
    """
    if not path.is_absolute():
        msg = f"{what} must be absolute: {path}"
        raise ValueError(msg)
    return Path(os.path.normpath(str(path)))


def _resolve_launch_home(launch_home: Path | None) -> Path:
    """Return the explicit or OS-resolved launch home as an absolute path.

    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:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Convert to absolute before calling: Path(value).resolve() or path.expanduser().resolve().
2. Set DEEPAGENTS_HOME to an absolute path (starting with / on POSIX, drive letter on Windows).
3. In config, anchor relative paths to a known base (home or project root) before passing them.

Example fix

// before
os.environ['DEEPAGENTS_HOME'] = 'deepagents-home'
// after
os.environ['DEEPAGENTS_HOME'] = str(Path('deepagents-home').resolve())

from pathlib import Path
def ensure_absolute(p: Path, what: str = 'Path') -> Path:
    if not p.is_absolute():
        raise ValueError(f'{what} must be absolute: {p}')
    return p

def is_absolute_path(p: Path) -> bool:
    return isinstance(p, Path) and p.is_absolute()

try:
    paths = project_paths(...)
except ValueError as exc:
    if 'must be absolute' in str(exc):
        # re-anchor the value to an absolute base and retry
        ...

When it happens

Trigger: 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'.

Common situations: 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').

Related errors

• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid DEEPAGENTS_HOME {str(root)!r}: exists but is not a d
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown fil
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• shell_allow_list must be None or non-empty

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