{"record":{"id":"ceec65247f792eb9","repo":"langchain-ai/deepagents","slug":"invalid-deepagents-home-str-root-r-exists-but-ceec65","errorCode":null,"errorMessage":"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but is not a directory.","messagePattern":"Invalid DEEPAGENTS_HOME (.+?): exists but is not a directory\\.","errorType":"exception","errorClass":"DeepAgentsHomeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/_paths.py","lineNumber":706,"sourceCode":"    it may not read, so checking state first reports the permission problem\n    itself instead of the comparison that failed because of it.\n\n    Raises:\n        DeepAgentsHomeError: If the root is one of those cases.\n    \"\"\"\n    state = classify_path(root)\n    if state is PathState.UNREADABLE:\n        # Checked before the symlink branch too: `Path.is_symlink` swallows the\n        # `OSError` and reports `False` under EACCES, so an unreadable root\n        # would otherwise fall through every check and be accepted.\n        msg = (\n            f\"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be read. \"\n            \"Check the permissions on it and on its parent directories.\"\n        )\n        raise DeepAgentsHomeError(msg)\n    if state is PathState.EXISTS and not root.is_dir():\n        msg = f\"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but is not a directory.\"\n        raise DeepAgentsHomeError(msg)\n    if state is PathState.EXISTS and not os.access(root, os.R_OK | os.X_OK):\n        msg = (\n            f\"Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be read \"\n            \"or searched. Check the permissions on it and on its parent \"\n            \"directories.\"\n        )\n        raise DeepAgentsHomeError(msg)\n    # `root` is normalized-absolute, so `anchor` is always set.\n    if root.parent == root or _same_directory(root, Path(root.anchor)):\n        msg = (\n            f\"Invalid DEEPAGENTS_HOME {str(root)!r}: the filesystem root cannot \"\n            \"be a profile. Use a dedicated directory.\"\n        )\n        raise DeepAgentsHomeError(msg)\n    if launch_home is not None and _same_directory(root, launch_home):\n        msg = (\n            f\"Invalid DEEPAGENTS_HOME {str(root)!r}: the home directory itself \"\n            \"cannot be a profile, because its '.env' would be loaded as \"","sourceCodeStart":688,"sourceCodeEnd":724,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/_paths.py#L688-L724","documentation":"An existing DEEPAGENTS_HOME must be a directory; if it exists but is a regular file, symlink-to-file, socket, etc., _reject_degenerate_root raises DeepAgentsHomeError. The profile root owns everything beneath it, so a non-directory cannot serve as the root.","triggerScenarios":"DEEPAGENTS_HOME points at a path that exists as a non-directory — e.g. a stray file named '.deepagents' created by a redirect (touch or command output) where a directory was expected.","commonSituations":"Shell redirect like 'cmd > ~/.deepagents' creating a file; tar/backup extraction leaving a file where the dir should be; typos pointing DEEPAGENTS_HOME at a config file path.","solutions":["Remove the offending file (rm <path>) and let the library create a directory there.","If the file holds data you need, move it elsewhere first, then re-run.","Point DEEPAGENTS_HOME at an intended directory instead of a file path."],"exampleFix":"// before: ~/.deepagents is a regular file\nmv ~/.deepagents ~/.deepagents.bak  # inspect, then discard\n// after: run the app; it mkdirs ~/.deepagents as a directory","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\nroot = Path(os.environ.get('DEEPAGENTS_HOME', ''))\nif root.exists() and not root.is_dir():\n    root.rename(root.with_suffix('.bak'))  # move the stray file aside","typeGuard":"def is_existing_dir(p: Path) -> bool:\n    return p.is_dir() and not p.is_symlink()","tryCatchPattern":"try:\n    root = _resolve_profile_root()\nexcept DeepAgentsHomeError as exc:\n    if 'is not a directory' in str(exc):\n        target = Path(os.environ['DEEPAGENTS_HOME'])\n        target.rename(target.with_suffix('.bak'))\n        root = _resolve_profile_root()\n    else:\n        raise","preventionTips":["Never redirect shell output to the profile-root path.","Check for stray files at expected directory locations after extractions.","Point DEEPAGENTS_HOME at directories, not config-file paths."],"tags":["filesystem","paths","configuration"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}