{"record":{"id":"a3c320500cea5b44","repo":"langchain-ai/deepagents","slug":"workspace-field-is-unavailable-value","errorCode":null,"errorMessage":"workspace.{field} is unavailable: {value}","messagePattern":"workspace\\.(.+?) is unavailable: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/workspace.py","lineNumber":86,"sourceCode":"\n\ndef _canonical_directory(value: object, *, field: str) -> Path:\n    if not isinstance(value, str) or not value or len(value) > _MAX_PATH_LENGTH:\n        msg = f\"workspace.{field} must be a non-empty absolute path\"\n        raise ValueError(msg)\n    candidate = Path(value)\n    if not candidate.is_absolute() or \"..\" in PurePath(value).parts:\n        msg = f\"workspace.{field} must be an absolute path without traversal\"\n        raise ValueError(msg)\n    if os.name != \"nt\":\n        from deepagents.backends.utils import validate_path\n\n        validate_path(value)\n    try:\n        resolved = candidate.resolve(strict=True)\n    except (OSError, RuntimeError) as exc:\n        msg = f\"workspace.{field} is unavailable: {value}\"\n        raise ValueError(msg) from exc\n    if not resolved.is_dir():\n        msg = f\"workspace.{field} is not a directory: {value}\"\n        raise ValueError(msg)\n    if os.name != \"nt\":\n        from deepagents.backends.utils import validate_path\n\n        validate_path(str(resolved))\n    return resolved\n\n\ndef canonical_workspace_config(value: object | None) -> tuple[str, str]:\n    \"\"\"Return bounded canonical JSON and its SHA-256 fingerprint.\n\n    Raises:\n        TypeError: If the configuration is not an object.\n        ValueError: If it cannot be serialized or exceeds the size limit.\n    \"\"\"\n    if value is None:","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/workspace.py#L68-L104","documentation":"Raised when the workspace path cannot be resolved on the filesystem: candidate.resolve(strict=True) raised OSError or RuntimeError, meaning the path (or a symlink target) does not exist or is inaccessible. The original exception is chained as __cause__. Note the path must exist; merely pointing at a valid-looking path is not enough.","triggerScenarios":"Calling resolve_workspace with workspace.{field} pointing at a nonexistent directory, a broken symlink, or a path in an unmounted/unreachable filesystem that raises during strict resolution.","commonSituations":"Typo in the directory name; directory deleted after being configured; network drive or external volume not mounted; broken symlink after moving a project.","solutions":["Create the directory first (mkdir -p) or correct the path to an existing one.","Fix or remove broken symlinks (ls -l to spot them).","Mount/remount the volume or reconnect the network drive before starting.","Check permissions along the path so strict resolve can traverse it."],"exampleFix":"// before\nresolve_workspace(workspace={'dir': '/home/me/gone-project'})\n// after\nmkdir -p /home/me/project\nresolve_workspace(workspace={'dir': '/home/me/project'})","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\nimport os\n\ndef path_exists(value: str) -> bool:\n    try:\n        Path(value).resolve(strict=True)\n        return True\n    except (OSError, RuntimeError):\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    ws = resolve_workspace(workspace={'dir': cfg['dir']})\nexcept ValueError as e:\n    logger.error('workspace unavailable: %s', e)\n    mkdir -p the directory or pick another path","preventionTips":["Create the directory before configuring it as a workspace","Check for broken symlinks after moving projects","Ensure network/external volumes are mounted at startup"],"tags":["filesystem","path","workspace"],"backgroundTag":"path-not-found","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}