Conversation history was offloaded to {file_path}, but {fail

Error message

Conversation history was offloaded to {file_path}, but {failed_media} media block(s) could not be offloaded and appear as failed placeholders in the saved history; the original media is not recoverable.

What it means

A UserWarning raised by the summarization middleware's sync `wrap_model_call`. When the conversation exceeds token thresholds, the middleware offloads older messages (including inline media) to a file in the configured backend before summarizing. This warning means the history file WAS written, but some media blocks (images, etc.) could not be offloaded and were saved only as failed placeholders — the original media bytes are lost and cannot be recovered from the saved history.

Source

Thrown at libs/deepagents/deepagents/middleware/summarization.py:1444

        session_id = self._get_session_id(request.state)

        # Offload to backend first so history is preserved before summarization.
        # If offload fails, summarization still proceeds (with file_path=None).
        file_path = self._offload_to_backend(backend, offloaded_media_messages, session_id)
        if file_path is None:
            msg = "Offloading conversation history to backend failed during summarization. Older messages will not be recoverable."
            logger.error(msg)
            warnings.warn(msg, stacklevel=2)
        elif failed_media:
            # History was saved, but some media became failed-offload placeholders.
            # Tie the warning to the saved file so the recovery pointer is honest.
            msg = (
                f"Conversation history was offloaded to {file_path}, but {failed_media} media "
                "block(s) could not be offloaded and appear as failed placeholders in the saved "
                "history; the original media is not recoverable."
            )
            logger.warning(msg)
            warnings.warn(msg, stacklevel=2)

        # Generate summary
        summary = self._create_summary(offloaded_media_messages)

        # Build summary message with file path reference
        new_messages = self._build_new_messages_with_path(summary, file_path)

        previous_event = request.state.get("_summarization_event")
        state_cutoff_index = self._compute_state_cutoff(previous_event, cutoff_index)

        # Create new summarization event
        new_event: SummarizationEvent = {
            "cutoff_index": state_cutoff_index,
            "summary_message": new_messages[0],  # The HumanMessage with summary  # ty: ignore[invalid-argument-type]
            "file_path": file_path,
        }

        # Modify request to use summarized messages

View on GitHub (pinned to a1af029e6e)

Solutions

Inspect the saved history file at the `file_path` in the warning to see which blocks are failed placeholders.
Check backend connectivity, credentials, and size limits — fix the upload failure so future media offloads succeed.
Re-upload or re-attach the original media if you still hold it (e.g. re-run the tool that produced it); the middleware cannot recover it.
Raise the summarization token threshold or pre-truncate large tool results so media offload triggers less often.
If the media is not needed for the rest of the session, treat the warning as informational and continue.

Example fix

// before
middleware = SummarizationMiddleware(backend=unreachable_backend)

// after
backend = StateBackend()  # or a reachable/credentialed store
middleware = SummarizationMiddleware(backend=backend, keep_messages=20)

Defensive patterns

Strategy: validation

Validate before calling

# verify the backend is writable before starting the session
from deepagents.backends import StateBackend
backend = build_backend()
probe = backend.write("/_healthcheck/probe.txt", b"ok")
assert not getattr(probe, "error", None), "backend not writable; media offload will fail"

Type guard

def backend_ok(backend) -> bool:
    try:
        result = backend.write("/_healthcheck/probe.txt", b"ok")
        return getattr(result, "error", None) is None
    except Exception:
        return False

Try / catch

import warnings
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    run_agent(...)
media_warnings = [w for w in caught if "media" in str(w.message) and "offloaded" in str(w.message)]
for w in media_warnings:
    file_path = str(w.message).split("offloaded to ")[1].split(",")[0]
    inspect_history_file(file_path)  # find failed placeholders and re-attach media

Prevention

Verify backend connectivity and credentials before long multimodal sessions.
Confirm the backend accepts your media payload sizes (object-store limits).
Tune summarization thresholds so offload happens under healthy storage conditions.
Keep original media (tool outputs, uploads) retrievable outside the agent history.
Treat `warnings` from the summarization middleware as signals, not noise — alert on them in production.

When it happens

Trigger: `SummarizationMiddleware.wrap_model_call` runs when `_should_summarize` is true (or a `ContextOverflowError` is caught), `_offload_inline_media` returns a non-empty `failed_media` count (a media block fails backend upload or encoding), yet `_offload_to_backend` succeeds (returns a `file_path`). The `failed_media` count and the saved `file_path` are interpolated into the message.

Common situations: Long agent sessions with image-bearing tool results or multimodal user messages that trip the token limit; a storage backend that rejects large or unsupported payloads (size limits, permissions, transient object-store errors); media blocks in message formats the offloader cannot serialize.

Related errors

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