langchain-ai/deepagents · error · DeepAgentsHomeError

Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be

Error message

Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be read. Check the permissions on it and on its parent directories.

What it means

_reject_degenerate_root validates an existing DEEPAGENTS_HOME path: it must be readable and searchable (os.access R_OK|X_OK) to be usable as a profile root. An existing but unreadable path is rejected with DeepAgentsHomeError because the library would otherwise silently accept a root it cannot inspect, and the profile root is a trust boundary.

Source

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

    cased spelling of `/` or of the home directory is rejected too.

    The readability check runs first. `_same_directory` cannot compare a path
    it may not read, so checking state first reports the permission problem
    itself instead of the comparison that failed because of it.

    Raises:
        DeepAgentsHomeError: If the root is one of those cases.
    """
    state = classify_path(root)
    if state is PathState.UNREADABLE:
        # Checked before the symlink branch too: `Path.is_symlink` swallows the
        # `OSError` and reports `False` under EACCES, so an unreadable root
        # would otherwise fall through every check and be accepted.
        msg = (
            f"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be read. "
            "Check the permissions on it and on its parent directories."
        )
        raise DeepAgentsHomeError(msg)
    if state is PathState.EXISTS and not root.is_dir():
        msg = f"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but is not a directory."
        raise DeepAgentsHomeError(msg)
    if state is PathState.EXISTS and not os.access(root, os.R_OK | os.X_OK):
        msg = (
            f"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be read "
            "or searched. Check the permissions on it and on its parent "
            "directories."
        )
        raise DeepAgentsHomeError(msg)
    # `root` is normalized-absolute, so `anchor` is always set.
    if root.parent == root or _same_directory(root, Path(root.anchor)):
        msg = (
            f"Invalid DEEPAGENTS_HOME {str(root)!r}: the filesystem root cannot "
            "be a profile. Use a dedicated directory."
        )
        raise DeepAgentsHomeError(msg)
    if launch_home is not None and _same_directory(root, launch_home):

View on GitHub (pinned to a1af029e6e)

Solutions

1. Restore access: chmod u+rx <path> (and fix ownership with chown if needed).
2. Fix parent-directory permissions so the path is traversable.
3. If the path is unusable, remove or rename it and set DEEPAGENTS_HOME to a fresh user-owned directory.

Example fix

// before
drwx------ root root /opt/deepagents-home
// after
sudo chown $(whoami) /opt/deepagents-home && chmod u+rwx /opt/deepagents-home

import os
from pathlib import Path
root = Path(os.environ.get('DEEPAGENTS_HOME', ''))
if root.exists() and not (os.access(root, os.R_OK | os.X_OK) and root.is_dir()):
    raise SystemExit(f'DEEPAGENTS_HOME {root} must be a readable directory')

try:
    root = _resolve_profile_root()
except DeepAgentsHomeError as exc:
    if 'cannot be read' in str(exc):
        raise SystemExit(f'Run: chmod u+rx {root} (and fix parents)') from exc
    raise

When it happens

Trigger: DEEPAGENTS_HOME set to an existing path that the current user cannot read or search (missing r or x permission) while _resolve_profile_root runs its checks.

Common situations: Directory restored from a backup with root ownership; chmod 000 applied by mistake; container volume mounted with restrictive uid ownership.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Cannot determine whether {str(left)!r} is {str(right)!r}: {e
• debug log directory is not owned by the current user: {path}
• Invalid DEEPAGENTS_HOME {str(root)!r}: exists but is not a d
• Failed to read credential file {path}: {exc}. Check the file
• Failed to write credential file {auth_path()}: {exc}. Check

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