_handle_failure() — langchain Function Reference

Architecture documentation for the _handle_failure() function in tool_retry.py from the langchain codebase.

Function python LangChainCore MessageInterface calls 1 called by 2

Entity Profile

LangChainCore→ MessageInterface→ _handle_failure() — langchain Function Reference

Dependency Diagram

graph TD
  7a031c34_097e_d25a_0210_cf5d0d368b98["_handle_failure()"]
  33f83a05_ad1b_0c1c_e484_ac91455db157["ToolRetryMiddleware"]
  7a031c34_097e_d25a_0210_cf5d0d368b98 -->|defined in| 33f83a05_ad1b_0c1c_e484_ac91455db157
  731777b2_3052_874d_7b48_c5d58d2e0a8c["wrap_tool_call()"]
  731777b2_3052_874d_7b48_c5d58d2e0a8c -->|calls| 7a031c34_097e_d25a_0210_cf5d0d368b98
  e9a8e4d0_4a9e_0f20_9c10_65fc4f8ed225["awrap_tool_call()"]
  e9a8e4d0_4a9e_0f20_9c10_65fc4f8ed225 -->|calls| 7a031c34_097e_d25a_0210_cf5d0d368b98
  a235f099_6804_8d79_50f5_13bbaa648627["_format_failure_message()"]
  7a031c34_097e_d25a_0210_cf5d0d368b98 -->|calls| a235f099_6804_8d79_50f5_13bbaa648627
  style 7a031c34_097e_d25a_0210_cf5d0d368b98 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/langchain_v1/langchain/agents/middleware/tool_retry.py lines 256–286

    def _handle_failure(
        self, tool_name: str, tool_call_id: str | None, exc: Exception, attempts_made: int
    ) -> ToolMessage:
        """Handle failure when all retries are exhausted.

        Args:
            tool_name: Name of the tool that failed.
            tool_call_id: ID of the tool call (may be `None`).
            exc: The exception that caused the failure.
            attempts_made: Number of attempts actually made.

        Returns:
            `ToolMessage` with error details.

        Raises:
            Exception: If `on_failure` is `'error'`, re-raises the exception.
        """
        if self.on_failure == "error":
            raise exc

        if callable(self.on_failure):
            content = self.on_failure(exc)
        else:
            content = self._format_failure_message(tool_name, exc, attempts_made)

        return ToolMessage(
            content=content,
            tool_call_id=tool_call_id,
            name=tool_name,
            status="error",
        )