{"record":{"id":"4bcea2eb58056178","repo":"langchain-ai/deepagents","slug":"workspace-field-must-be-a-non-empty-absolute-pat","errorCode":null,"errorMessage":"workspace.{field} must be a non-empty absolute path","messagePattern":"workspace\\.(.+?) must be a non-empty absolute path","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/workspace.py","lineNumber":73,"sourceCode":"\n\nclass WorkspaceConflictError(RuntimeError):\n    \"\"\"A thread was claimed from a different workspace or resource policy.\"\"\"\n\n\ndef _database_path() -> Path:\n    value = os.environ.get(f\"{SERVER_ENV_PREFIX}DB_PATH\")\n    if value:\n        return Path(value)\n    from deepagents_code.sessions import get_db_path\n\n    return get_db_path()\n\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","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/workspace.py#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Provide a non-empty absolute string path for the workspace field.","Convert Path objects to str(...) before calling resolve_workspace.","Shorten overly long paths (move the workspace or shorten ancestor directory names).","Default unset env/config values to an explicit absolute path."],"exampleFix":"// before\nresolve_workspace(workspace={'dir': ''})\n// after\nresolve_workspace(workspace={'dir': '/home/me/project'})","handlingStrategy":"type-guard","validationCode":"_MAX = 4096\ndef check(value):\n    if not isinstance(value, str) or not value or len(value) > _MAX:\n        raise ValueError('workspace path must be a non-empty absolute path string')\n    return str(value)","typeGuard":"def is_valid_workspace_str(value: object) -> bool:\n    return isinstance(value, str) and bool(value) and len(value) <= 4096","tryCatchPattern":"try:\n    ws = resolve_workspace(workspace={'dir': cfg['dir']})\nexcept ValueError as e:\n    logger.error('bad workspace config: %s', e)","preventionTips":["Always pass str, never Path objects, into workspace fields","Provide explicit non-empty defaults for unset env/config values","Check path length limits when using deeply nested directories on Windows"],"tags":["validation","path","workspace"],"backgroundTag":"invalid-path","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}