Error Handling

Structured exceptions tell you what failed, whether to retry, and which agent or run was involved — without parsing raw tracebacks.

from praisonaiagents import Agent, PraisonAIError

agent = Agent(name="assistant", instructions="Be helpful")

try:
    print(agent.start("Say hello in one sentence."))
except PraisonAIError as e:
    print(f"{e.error_category}: {e.message} (agent={e.agent_id}, run={e.run_id})")

The user runs the agent; failures raise typed PraisonAIError with category, message, and run context for recovery.

Quick Start

Catch any agent error

from praisonaiagents import Agent, PraisonAIError

agent = Agent(name="assistant", instructions="Be helpful")

try:
    result = agent.start("Say hello in one sentence.")
    print(result)
except PraisonAIError as e:
    print(f"{e.error_category}: {e.message} (agent={e.agent_id}, run={e.run_id})")

Handle tool errors specifically

from praisonaiagents import Agent, tool, ToolExecutionError

@tool
def divide(a: float, b: float) -> float:
    """Divide two numbers."""
    return a / b

agent = Agent(instructions="Use divide.", tools=[divide])

try:
    agent.start("Divide 10 by 0.")
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e.message}")
    print(f"Retryable: {e.is_retryable}")

Catch a failed LLM tool-calling loop

from praisonaiagents import Agent
from praisonaiagents.llm import LLMResponseError

agent = Agent(name="assistant", instructions="Answer clearly.")

try:
    result = agent.start("Summarise the latest project update.")
except LLMResponseError as e:
    # A mid-loop tool-calling error now raises instead of returning ""
    print(f"LLM call failed: {e.message}")

How It Works

Every structured error carries message, agent_id, run_id, error_category, and is_retryable. Subclasses add domain fields such as tool_name or model_name.

Class	When raised	Key fields	Default retryable
`PraisonAIError`	Base — catch-all	`error_category`, `context`	`False`
`ToolExecutionError`	Tool fails or loop-guard `HALT`	`tool_name`	`True`
`LLMError`	Chat completion fails	`model_name`	`False`
`ValidationError`	Invalid config or input	`field_name`	`False`
`NetworkError`	External service unreachable	`service_name`, `status_code`	`True`
`LLMResponseError`	LLM tool-calling loop fails mid-iteration	`__cause__` (chained)	`False`

error_category uses typed kinds such as rate_limit, auth, context_overflow, and billing. LLMResponseError is raised by LLM.get_response() when the tool-calling loop fails and cannot produce a response — previously this was swallowed and returned as an empty string. Catch it to distinguish tool-loop failures; a try/except Exception already covers it. See LLMResponseError.

LLM Response Errors

LLMResponseError is raised when the LLM tool-calling loop hits an exception it cannot recover from. It lives in praisonaiagents.llm alongside the other LLM exceptions:

from praisonaiagents.llm import LLMResponseError

Behaviour change: a mid-loop tool-calling failure now raises LLMResponseError. Previously the loop swallowed the exception and returned an empty string (""), so agent.start() / agent.chat() looked like they succeeded while silently persisting an empty assistant message and burning retries. Wrap calls that must distinguish a real failure from an empty answer.

Exception	Module	Raised when
`LLMResponseError`	`praisonaiagents.llm`	The tool-calling loop in `LLM.get_response()` fails mid-iteration and surfaces to the caller
`LLMContextLengthExceededException`	`praisonaiagents.llm`	The prompt exceeds the model’s context window

LLMResponseError carries a message attribute describing the iteration that failed and chains the original exception via raise … from e, so e.__cause__ holds the underlying error.

Common Patterns

Retry on transient network failures, fail on config bugs:

from praisonaiagents import Agent, NetworkError, ValidationError

agent = Agent(name="assistant")

for attempt in range(3):
    try:
        print(agent.start("Summarise today's news."))
        break
    except NetworkError:
        if attempt == 2:
            raise
    except ValidationError:
        raise  # fix config — retry won't help

Raised errors stop the run; some callbacks record failures on the output instead. See Non-Fatal Errors.

Reaching the Step Limit

When the tool-calling loop reaches ExecutionConfig.max_steps (or max_iter when max_steps is unset), the agent does not hard-cut. On the final permitted step it injects a graceful wrap-up instruction, so the model returns a real summary of what it accomplished and what remains — not a placeholder. Detect truncation with agent.last_stop_reason instead of string-matching:

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="coder",
    instructions="You are a coding assistant.",
    execution=ExecutionConfig(max_steps=50),
)
result = agent.start("Refactor the auth module across all files")

if agent.last_stop_reason == "max_steps":
    result = agent.start("Continue from where you left off.")

On a gateway, surface the reason to chat users — see Turn Completion Notes.

Step Budget

Cap tool-use steps and detect graceful truncation with last_stop_reason

Best Practices

Catch the most specific class you can handle

Use ToolExecutionError when you only care about tool failures; reserve PraisonAIError for top-level logging.

Log structured context

Include e.error_category, e.agent_id, and e.run_id in observability hooks — they correlate across multi-agent runs.

Don't swallow ValidationError

Validation failures usually mean a programming or config bug. Fix the root cause instead of retrying blindly.

Pair with loop guard for retry loops

Loop-guard HALT raises ToolExecutionError. Combine with Loop Guard when tools may repeat indefinitely.

Treat an LLMResponseError as a real failure, not an empty answer

A failed tool-calling loop now raises LLMResponseError instead of returning "". Catch it explicitly (from praisonaiagents.llm import LLMResponseError) so retries and observability see the actual error rather than a silent empty string.

Loop Guard

Stop runaway tool loops with HALT/WARN/BLOCK

Non-Fatal Errors

Callback failures captured without crashing

Non-Fatal Errors

Structured LLM Errors

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

LLM Response Errors

Common Patterns

Reaching the Step Limit

Step Budget

Best Practices

Loop Guard

Non-Fatal Errors

​Quick Start

​How It Works

​LLM Response Errors

​Common Patterns

​Reaching the Step Limit

Step Budget

​Best Practices

​Related

Loop Guard

Non-Fatal Errors

Quick Start

How It Works

LLM Response Errors

Common Patterns

Reaching the Step Limit

Best Practices

Related