Skip to content

Exceptions

All Zap exceptions inherit from ZapError.

Exception Hierarchy

ZapError
├── ZapConfigurationError
├── ZapNotStartedError
├── AgentNotFoundError
├── TaskNotFoundError
├── ToolNotFoundError
├── ToolExecutionError
├── ClientConnectionError
├── SchemaConversionError
└── LLMProviderError

ZapError

zap_ai.exceptions.ZapError

Bases: Exception

Base exception for all Zap errors.

Source code in src/zap_ai/exceptions.py 
 8
 9
10
11
class ZapError(Exception):
    """Base exception for all Zap errors."""

    pass

Configuration Errors

zap_ai.exceptions.ZapConfigurationError

Bases: ZapError

Raised when Zap configuration is invalid.

Source code in src/zap_ai/exceptions.py 
19
20
21
22
class ZapConfigurationError(ZapError):
    """Raised when Zap configuration is invalid."""

    pass

zap_ai.exceptions.ZapNotStartedError

Bases: ZapError

Raised when operations are attempted before calling start().

Source code in src/zap_ai/exceptions.py 
25
26
27
28
class ZapNotStartedError(ZapError):
    """Raised when operations are attempted before calling start()."""

    pass

Not Found Errors

zap_ai.exceptions.AgentNotFoundError

Bases: ZapError

Raised when referencing an agent that doesn't exist.

Source code in src/zap_ai/exceptions.py 
31
32
33
34
class AgentNotFoundError(ZapError):
    """Raised when referencing an agent that doesn't exist."""

    pass

zap_ai.exceptions.TaskNotFoundError

Bases: ZapError

Raised when referencing a task that doesn't exist.

Source code in src/zap_ai/exceptions.py 
37
38
39
40
class TaskNotFoundError(ZapError):
    """Raised when referencing a task that doesn't exist."""

    pass

zap_ai.exceptions.ToolNotFoundError

Bases: ZapError

Raised when a tool cannot be found.

Source code in src/zap_ai/exceptions.py 
48
49
50
51
class ToolNotFoundError(ZapError):
    """Raised when a tool cannot be found."""

    pass

Execution Errors

zap_ai.exceptions.ToolExecutionError

Bases: ZapError

Raised when tool execution fails.

Source code in src/zap_ai/exceptions.py 
54
55
56
57
class ToolExecutionError(ZapError):
    """Raised when tool execution fails."""

    pass

zap_ai.exceptions.ClientConnectionError

Bases: ZapError

Raised when MCP client connection fails.

Source code in src/zap_ai/exceptions.py 
60
61
62
63
class ClientConnectionError(ZapError):
    """Raised when MCP client connection fails."""

    pass

zap_ai.exceptions.SchemaConversionError

Bases: ZapError

Raised when schema conversion fails.

Source code in src/zap_ai/exceptions.py 
66
67
68
69
class SchemaConversionError(ZapError):
    """Raised when schema conversion fails."""

    pass

zap_ai.exceptions.LLMProviderError

Bases: ZapError

Raised when LLM provider call fails.

Source code in src/zap_ai/exceptions.py 
77
78
79
80
class LLMProviderError(ZapError):
    """Raised when LLM provider call fails."""

    pass

Handling Errors

from zap_ai import Zap, ZapAgent
from zap_ai.exceptions import (
    ZapNotStartedError,
    AgentNotFoundError,
    TaskNotFoundError,
)

zap = Zap(agents=[...])

try:
    # This will fail - Zap not started
    await zap.execute_task(agent_name="Test", task="Hello")
except ZapNotStartedError:
    print("Call zap.start() first!")

await zap.start()

try:
    # This will fail - agent doesn't exist
    await zap.execute_task(agent_name="NonExistent", task="Hello")
except AgentNotFoundError as e:
    print(f"Agent not found: {e}")

try:
    # This will fail - task doesn't exist
    await zap.get_task("invalid-task-id")
except TaskNotFoundError:
    print("Task not found")