What causes "workspace.{field} is unavailable: {value}" in langchain-ai/deepagents?

Create the directory first (mkdir -p) or correct the path to an existing one.

langchain-ai/deepagents · error · ValueError

workspace.{field} is unavailable: {value}

Error message

workspace.{field} is unavailable: {value}

What it means

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.

Source

Thrown at libs/code/deepagents_code/workspace.py:86


def _canonical_directory(value: object, *, field: str) -> Path:
    if not isinstance(value, str) or not value or len(value) > _MAX_PATH_LENGTH:
        msg = f"workspace.{field} must be a non-empty absolute path"
        raise ValueError(msg)
    candidate = Path(value)
    if not candidate.is_absolute() or ".." in PurePath(value).parts:
        msg = f"workspace.{field} must be an absolute path without traversal"
        raise ValueError(msg)
    if os.name != "nt":
        from deepagents.backends.utils import validate_path

        validate_path(value)
    try:
        resolved = candidate.resolve(strict=True)
    except (OSError, RuntimeError) as exc:
        msg = f"workspace.{field} is unavailable: {value}"
        raise ValueError(msg) from exc
    if not resolved.is_dir():
        msg = f"workspace.{field} is not a directory: {value}"
        raise ValueError(msg)
    if os.name != "nt":
        from deepagents.backends.utils import validate_path

        validate_path(str(resolved))
    return resolved


def canonical_workspace_config(value: object | None) -> tuple[str, str]:
    """Return bounded canonical JSON and its SHA-256 fingerprint.

    Raises:
        TypeError: If the configuration is not an object.
        ValueError: If it cannot be serialized or exceeds the size limit.
    """
    if value is None:

View on GitHub (pinned to a1af029e6e)

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.

Example fix

// before
resolve_workspace(workspace={'dir': '/home/me/gone-project'})
// after
mkdir -p /home/me/project
resolve_workspace(workspace={'dir': '/home/me/project'})

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
import os

def path_exists(value: str) -> bool:
    try:
        Path(value).resolve(strict=True)
        return True
    except (OSError, RuntimeError):
        return False

Try / catch

try:
    ws = resolve_workspace(workspace={'dir': cfg['dir']})
except ValueError as e:
    logger.error('workspace unavailable: %s', e)
    mkdir -p the directory or pick another path

Prevention

Create the directory before configuring it as a workspace
Check for broken symlinks after moving projects
Ensure network/external volumes are mounted at startup

When it happens

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

Common situations: Typo in the directory name; directory deleted after being configured; network drive or external volume not mounted; broken symlink after moving a project.

Related errors

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