langchain-ai/deepagents · error · ValueError

workspace.{field} must be a non-empty absolute path

Error message

workspace.{field} must be a non-empty absolute path

What it means

Raised when a workspace field value is not a non-empty string within the maximum path length. resolve_workspace delegates to _canonical_directory, which requires a str path before it can build a Path candidate. Empty strings, non-string values (None, Path objects passed to a str field), or overlong paths are rejected.

Source

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

class WorkspaceConflictError(RuntimeError):
    """A thread was claimed from a different workspace or resource policy."""


def _database_path() -> Path:
    value = os.environ.get(f"{SERVER_ENV_PREFIX}DB_PATH")
    if value:
        return Path(value)
    from deepagents_code.sessions import get_db_path

    return get_db_path()


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

View on GitHub (pinned to a1af029e6e)

Solutions

1. Provide a non-empty absolute string path for the workspace field.
2. Convert Path objects to str(...) before calling resolve_workspace.
3. Shorten overly long paths (move the workspace or shorten ancestor directory names).
4. Default unset env/config values to an explicit absolute path.

Example fix

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

_MAX = 4096
def check(value):
    if not isinstance(value, str) or not value or len(value) > _MAX:
        raise ValueError('workspace path must be a non-empty absolute path string')
    return str(value)

def is_valid_workspace_str(value: object) -> bool:
    return isinstance(value, str) and bool(value) and len(value) <= 4096

try:
    ws = resolve_workspace(workspace={'dir': cfg['dir']})
except ValueError as e:
    logger.error('bad workspace config: %s', e)

When it happens

Trigger: Calling resolve_workspace with workspace.{field} set to None, an empty string '', a non-str (e.g. int or Path), or a string longer than _MAX_PATH_LENGTH.

Common situations: Missing config entry defaulting to empty string; env var unset and interpolated as empty; programmatic callers passing Path objects where a str is required; path exceeding OS length limits (common on Windows deep trees).

Related errors

• workspace.{field} must be an absolute path without traversal
• workspace.{field} is not a directory: {value}
• Workspace policy and fingerprint must be configured together
• Path does not exist: {path}
• user_cwd must be absolute, got {self.user_cwd!r}

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