langchain-ai/deepagents · error · NotImplementedError

NotImplementedError raised by abstract `delete` (backend doe

Error message

NotImplementedError raised by abstract `delete` (backend does not implement `delete`)

What it means

`BackendProtocol.delete` is an optional capability: backends that don't override it inherit this base-class stub, which raises `NotImplementedError` when called. Deletion (recursive removal of a path or prefix) is not supported by every backend, so the protocol deliberately defaults to raising rather than silently failing. The docstring tells callers to guard with `supports_delete` or catch `NotImplementedError`.

Source

Thrown at libs/deepagents/deepagents/backends/protocol.py:748

        Deletion is recursive: it removes `file_path` plus everything nested
        under it. On hierarchical backends (e.g.
        [`FilesystemBackend`][deepagents.backends.filesystem.FilesystemBackend])
        that means a directory and its contents; on key-value backends it means
        the exact key plus every key sharing the `file_path` + "/" prefix.

        Args:
            file_path: Absolute path to delete (a file, or a directory/prefix to
                remove recursively). Must start with '/'.

        Returns:
            `DeleteResult` with the deleted path on success, or an error if
                nothing exists at or under the path or removal fails.

        Raises:
            NotImplementedError: If the backend does not implement `delete`.
        """
        raise NotImplementedError

    async def adelete(self, file_path: str) -> DeleteResult:
        """Async version of `delete`."""
        return await asyncio.to_thread(self.delete, file_path)

    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
        """Upload multiple files to the sandbox.

        This API is designed to allow developers to use it either directly or by
        exposing it to LLMs via custom tools.

        Args:
            files: List of (path, content) tuples to upload.

        Returns:
            List of `FileUploadResponse` objects, one per input file.

                Response order matches input order (`response[i] for files[i]`).

View on GitHub (pinned to a1af029e6e)

Solutions

Check support first with `supports_delete(backend)` (or `type(backend).delete is not BackendProtocol.delete`) before calling
Wrap the call in try/except NotImplementedError and return a 'delete unsupported' result for mixed-backend code
Switch to a backend that implements delete, e.g. FilesystemBackend
Implement `delete` in your custom backend subclass

Example fix

// before
result = backend.delete('/tmp/scratch')

// after
from deepagents.backends.protocol import supports_delete
if supports_delete(backend):
    result = backend.delete('/tmp/scratch')
else:
    result = DeleteResult(error='delete not supported by this backend')

Defensive patterns

Strategy: validation

Validate before calling

from deepagents.backends.protocol import BackendProtocol

def supports_delete(backend: BackendProtocol) -> bool:
    return type(backend).delete is not BackendProtocol.delete

if not supports_delete(backend):
    raise RuntimeError(f'{type(backend).__name__} does not support delete')

Type guard

def is_deletable(backend) -> bool:
    return type(backend).delete is not BackendProtocol.delete

Try / catch

from deepagents.backends.protocol import DeleteResult
try:
    result = backend.delete(path)
except NotImplementedError:
    result = DeleteResult(files=[], error='delete not supported by this backend')

Prevention

Always guard optional backend capabilities with supports_* style checks before calling
When writing a custom backend, decide explicitly which optional methods (delete, upload_files, download_files) you implement and document the rest as unsupported
Add a capability smoke test per backend in CI

When it happens

Trigger: Calling `backend.delete(path)` (or `await backend.adelete(path)`) on a backend class that does not override `delete`, e.g. a minimal custom `BackendProtocol` subclass or a key-value backend without delete support. Also hit indirectly by tools/middleware that route delete operations to a backend lacking the capability.

Common situations: Writing a custom backend and forgetting to implement `delete`; switching a deep agent from a filesystem backend to a state/store backend that doesn't support deletion; generic code paths that assume all backends can delete.

Related errors

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