langchain-ai/deepagents · error · RuntimeError

archive read failed for {path}: {response.error}

Error message

archive read failed for {path}: {response.error}

What it means

When reading the archive snapshot, any backend-reported error other than FILE_NOT_FOUND is fatal: `_previous_content` raises RuntimeError embedding the path and the backend's error string. The offload write path refuses to continue because it cannot establish the prior archive content needed for a safe append/rollback.

Source

Thrown at libs/code/deepagents_code/offload_middleware.py:577

    async def _previous_content(self, path: str) -> tuple[bool, str]:
        """Read the archive snapshot needed to undo an uncommitted append.

        Returns:
            Whether the archive existed and its prior UTF-8 content.

        Raises:
            RuntimeError: If the backend cannot return the archive snapshot.
        """
        responses = await self.backend.adownload_files([path])
        if not responses:
            msg = f"archive backend returned no response for {path}"
            raise RuntimeError(msg)
        response = responses[0]
        if response.error == FILE_NOT_FOUND:
            return False, ""
        if response.error is not None:
            msg = f"archive read failed for {path}: {response.error}"
            raise RuntimeError(msg)
        content = response.content or b""
        return True, content.decode("utf-8")

    async def write(self) -> _ArchiveAppend | None:
        """Append staged messages and retain enough state for rollback.

        Returns:
            The reversible append, or `None` when the SDK could not write it.
        """
        path = self.summarization._get_history_path(self.session_id)
        existed, previous = await self._previous_content(path)
        guard = cast("BackendProtocol", _ArchiveReadGuard(self.backend))
        written_path = await self.summarization._aoffload_to_backend(
            guard, self.messages, self.session_id
        )
        append = _ArchiveAppend(self.backend, path, existed, previous)
        if written_path is None:
            await append.rollback()

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Read the backend error in the message and fix the underlying cause (credentials, network, permissions).
  2. Retry the offload once connectivity is restored — the write aborted before mutating state.
  3. Verify the archive backend is healthy and the archive path exists/is readable.

Example fix

// check before offloading
resp = await backend.adownload_files([archive_path])
if resp and resp[0].error not in (None, FILE_NOT_FOUND):
    raise RuntimeError(f"archive unavailable: {resp[0].error}")  # fix credentials/network first
Defensive patterns

Strategy: retry

Validate before calling

resp = (await backend.adownload_files([path]) or [None])[0]
if resp is not None and resp.error not in (None, FILE_NOT_FOUND):
    raise ArchiveUnavailable(f"precheck failed for {path}: {resp.error}")

Type guard

def is_readable(resp: FileDownloadResponse | None) -> bool:
    return resp is not None and resp.error in (None, FILE_NOT_FOUND)

Try / catch

try:
    await offload(thread_id)
except RuntimeError as e:
    if "archive read failed" in str(e):
        await refresh_backend_credentials()
        await offload(thread_id)  # safe: write aborted before mutating state
    else:
        raise

Prevention

When it happens

Trigger: `adownload_files` returns a response with a non-FILE_NOT_FOUND `error` (permission denied, timeout, deserialization failure, corrupted record) while a `/offload` write appends staged messages.

Common situations: Expired cloud-storage credentials; network partition between server and archive store; archive file corrupted or locked by another process; wrong archive path configuration pointing at inaccessible locations.

Related errors

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