langchain-ai/deepagents · error · ValueError

Failed to download {path}: {response.error}

Error message

Failed to download {path}: {response.error}

What it means

In MemoryMiddleware.before_agent, memory source files are fetched via backend.download_files. If a download response carries an error other than "file_not_found" (which is skipped), ValueError is raised with the path and backend error. Not-found sources are tolerated; other backend failures are not.

Source

Thrown at libs/deepagents/deepagents/middleware/memory.py:306

            config: Runnable config.

        Returns:
            State update with memory_contents populated.
        """
        # Skip if already loaded
        if "memory_contents" in state:
            return None

        backend = self._backend
        contents: dict[str, str] = {}

        results = backend.download_files(list(self.sources))
        for path, response in zip(self.sources, results, strict=True):
            if response.error is not None:
                if response.error == "file_not_found":
                    continue
                msg = f"Failed to download {path}: {response.error}"
                raise ValueError(msg)
            if response.content is not None:
                contents[path] = response.content.decode("utf-8")
                logger.debug("Loaded memory from: %s", path)

        return MemoryStateUpdate(memory_contents=contents)

    async def abefore_agent(self, state: MemoryState, runtime: Runtime, config: RunnableConfig) -> MemoryStateUpdate | None:  # ty: ignore[invalid-method-override]  # noqa: ARG002
        """Load memory content before agent execution.

        Loads memory from all configured sources and stores in state.
        Only loads if not already present in state.

        Args:
            state: Current agent state.
            runtime: Runtime context.
            config: Runnable config.

        Returns:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read response.error in the message and fix the underlying backend issue for that path
2. Verify the path is a readable file, not a directory, in the configured backend
3. Remove or correct the bad entry in the sources list
4. Catch ValueError in your agent setup and degrade gracefully

Example fix

// before
mw = MemoryMiddleware(backend=backend, sources=["notes/"])
// after
mw = MemoryMiddleware(backend=backend, sources=["notes/memory.md"])  # a real, readable file path

# pre-check sources via the backend before agent startup
results = backend.download_files(list(sources))
bad = [p for p, r in zip(sources, results) if r.error not in (None, "file_not_found")]
if bad:
    raise ValueError(f"Unreadable memory sources: {bad}")

def source_readable(path, backend) -> bool:
    r = backend.download_files([path])[0]
    return r.error in (None, "file_not_found")

try:
    agent = create_agent(middleware=[MemoryMiddleware(backend=backend, sources=sources)])
except ValueError as e:
    if e.args and e.args[0].startswith("Failed to download"):
        logger.warning("Memory load failed, continuing without memory: %s", e)
    else:
        raise

When it happens

Trigger: A source path exists in config but the backend fails to read it for reasons other than absence — e.g. permission denied, backend outage, serialization error, or a corrupted file record in a store-backed backend.

Common situations: Configured memory path points to a directory instead of a file, backend permissions changed, or a remote/store backend returns an unexpected error string.

Related errors

• NotImplementedError raised by abstract `download_files` (bac
• backend must be an initialized backend instance. Backend fac
• system_prompt must be str or None, got {type(system_prompt).
• system_prompt must contain the `{agent_memory}` format slot
• modes can only be provided when agent is a factory

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