What causes "Run {status}: {error_msg}" in BerriAI/litellm?

Inspect the error text — it is Azure's last_error.message and names the actual failure (e.g. which tool failed).

BerriAI/litellm · error · AzureAIAgentsError

Run {status}: {error_msg}

Error message

Run {status}: {error_msg}

What it means

For non-streaming Azure AI Agents completions, LiteLLM creates a run on a thread and polls its status. If the Azure run reports a terminal status of 'failed', 'cancelled', or 'expired' instead of 'completed', it raises AzureAIAgentsError with status_code 500 and a message combining the run status with last_error.message from the run resource. The root cause lives in the Azure agent run (tool errors, content filter, quota), not in LiteLLM.

Source

Thrown at litellm/llms/azure_ai/agents/handler.py:344

        response = make_request("POST", self._build_runs_url(api_base, thread_id, api_version), run_payload)
        self._check_response(response, [200, 201], "Failed to create run")
        run_id: Final = response.json()["id"]
        verbose_logger.debug("Created run: %s", run_id)

        # Step 4: Poll for completion
        status_url: Final = self._build_run_status_url(api_base, thread_id, run_id, api_version)
        for _ in range(self.config.MAX_POLL_ATTEMPTS):
            response = make_request("GET", status_url)
            self._check_response(response, [200], "Failed to get run status")

            status = response.json().get("status")
            verbose_logger.debug("Run status: %s", status)

            if status == "completed":
                break
            elif status in ["failed", "cancelled", "expired"]:
                error_msg = response.json().get("last_error", {}).get("message", "Unknown error")
                raise AzureAIAgentsError(status_code=500, message=f"Run {status}: {error_msg}")

            time.sleep(self.config.POLL_INTERVAL_SECONDS)
        else:
            raise AzureAIAgentsError(status_code=408, message="Run timed out waiting for completion")

        # Step 5: Get messages
        response = make_request("GET", self._build_list_messages_url(api_base, thread_id, api_version))
        self._check_response(response, [200], "Failed to get messages")

        content, annotations = self._extract_content_from_messages(response.json())
        return thread_id, content, annotations

    # -------------------------------------------------------------------------
    # Async Completion
    # -------------------------------------------------------------------------
    async def acompletion(
        self,
        model: str,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Inspect the error text — it is Azure's last_error.message and names the actual failure (e.g. which tool failed).
For 'failed': test the same agent in Azure AI Foundry playground; fix tool definitions/instructions there, LiteLLM only relays the failure.
For 'cancelled': check whether another process or person cancelled the run; retry if unintended.
For 'expired': reduce run latency (smaller inputs, faster tools) or re-submit the run on a fresh thread.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    thread_id, content, annotations = handler_completion(...)
except Exception as e:
    if type(e).__name__ == 'AzureAIAgentsError' and str(e).startswith(('Run failed', 'Run cancelled', 'Run expired')):
        handle_run_outcome(e.message)  # surface Azure last_error to caller / alerting
    raise

Prevention

Test every agent tool in the Foundry playground before wiring it into production calls.
Keep run inputs small enough that tools finish well inside your latency budget.
Tag cancelled runs to distinguish user action from Azure-side failure in logs.

When it happens

Trigger: Agent run whose tool call raised on the Azure side (failed); run cancelled by another client or the Foundry portal (cancelled); thread/run exceeded Azure's retention window so the run expired (expired). Typical with agents that call user-defined tools, code interpreter, or hit content-filter policies.

Common situations: Misconfigured tool definitions on the agent; agent instructed to call a function you never wired on Azure; run queued longer than the expiry window under load; someone cancels the run in the portal while debugging; OpenAI tool schema changes after a model upgrade on the Azure side.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/9cfbbbacf4574567. Report an issue: GitHub.