Skip to content

Errors & Exceptions

YosrAI provides educational error handling with helpful suggestions and documentation links.

Error Hierarchy

YosraiError (base)
├── ConfigurationError
├── LLMError
│   ├── LLMConnectionError
│   └── LLMContextError
├── ToolError
│   ├── ToolNotFoundError
│   └── ToolExecutionError
└── WorkflowError

Configuration Errors

Missing API Key

from yosrai import Agent

try:
    agent = Agent(model="openai/gpt-4o")  # No API key
except ConfigurationError as e:
    print(e)
    # Output:
    # API key for 'openai' not found.
    # 💡 Suggestion: Set the OPENAI_API_KEY environment variable or pass api_key to Agent().
    # 📚 Docs: https://yosrai.dev/docs/guide/quickstart#api-keys

Invalid Model

try:
    agent = Agent(model="unknown/model")
except ConfigurationError as e:
    print(e)
    # Output:
    # Invalid model 'unknown/model' for provider 'unknown'.
    # 💡 Suggestion: Use format 'provider/model' (e.g. 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet').
    # 📚 Docs: https://yosrai.dev/docs/reference/config#models

LLM Errors

Connection Issues

try:
    agent.run("Hello")
except LLMConnectionError as e:
    print(e)
    # Output:
    # Connection to openai timed out after 30s.
    # 💡 Suggestion: Check your internet connection or increase the timeout in AgentConfig.
    # 📚 Docs: https://yosrai.dev/docs/reference/config#timeout

Context Window Exceeded

try:
    agent.run("Very long input...")
except LLMContextError as e:
    print(e)
    # Output:
    # Context length (150000 tokens) exceeds model limit (128000 tokens).
    # 💡 Suggestion: Reduce message history with max_context_messages or use a model with larger context.
    # 📚 Docs: https://yosrai.dev/docs/reference/config#context-window

Tool Errors

Tool Not Found

try:
    agent.run("Use unknown_tool")
except ToolNotFoundError as e:
    print(e)
    # Output:
    # Tool 'unknown_tool' not found.
    # 💡 Suggestion: Available tools: calculate, search. Check your @tool decorator.
    # 📚 Docs: https://yosrai.dev/docs/reference/tools

Tool Execution Failed

try:
    agent.run("Calculate something")
except ToolExecutionError as e:
    print(e)
    # Output:
    # Tool 'calculate' failed: division by zero
    # 💡 Suggestion: Check your tool function for bugs. The error above shows what went wrong.
    # 📚 Docs: https://yosrai.dev/docs/reference/tools#error-handling

Workflow Errors

Empty Workflow

from yosrai import Workflow

try:
    wf = Workflow("Empty")
    wf.run()  # No steps added
except WorkflowError as e:
    print(e)
    # Output:
    # Cannot run an empty workflow.
    # 💡 Suggestion: Add steps with workflow.start(agent) before calling run().
    # 📚 Docs: https://yosrai.dev/docs/reference/workflow

Rich Error Display

All errors support rich formatting:

try:
    # Some operation
    pass
except YosraiError as e:
    e.rich_print()  # Fancy formatted output with colors and panels

API Reference

yosrai.engine.core.errors.YosraiError

Bases: Exception

Base class for all YosrAI exceptions.

Attributes:

Name Type Description
message

What went wrong
suggestion

How to fix it (optional)
doc_link

Documentation link (optional)
original_error

The underlying exception if any

__str__()

Format error with suggestion and doc link.

rich_print()

Print error with rich formatting if available.

yosrai.engine.core.errors.ConfigurationError

Bases: YosraiError

Raised when configuration is invalid (e.g. missing API keys).

invalid_model(model, provider) classmethod

Create error for invalid model string.

missing_api_key(provider) classmethod

Create error for missing API key.

yosrai.engine.core.errors.LLMError

Bases: YosraiError

Base class for LLM-related errors.

yosrai.engine.core.errors.ToolError

Bases: YosraiError

Base class for Tool execution errors.

yosrai.engine.core.errors.WorkflowError

Bases: YosraiError

Raised when workflow orchestration fails.