Exceptions¶
All Machina exceptions inherit from MachinaError, so a single except MachinaError catches everything framework-level while still letting unrelated exceptions surface.
The hierarchy is grouped by concern: connector errors, domain validation errors, agent runtime errors. Workflow execution errors and sandbox policy violations are top-level under MachinaError.
Root¶
MachinaError¶
MachinaError ¶
Bases: Exception
Base exception for all Machina errors.
Connector errors¶
All connector errors derive from ConnectorError. Catch the root if you don't care about the specific failure mode; catch the leaves when the recovery action differs.
ConnectorError¶
ConnectorError ¶
Bases: MachinaError
Error communicating with an external system via a connector.
ConnectorAuthError¶
ConnectorAuthError ¶
Bases: ConnectorError
Authentication or authorization failure in a connector.
ConnectorTimeoutError¶
ConnectorTimeoutError ¶
Bases: ConnectorError
A connector operation timed out.
ConnectorConfigError¶
ConnectorConfigError ¶
Bases: ConnectorError
A connector's configuration is invalid or incomplete.
ConnectorSchemaError¶
ConnectorSchemaError ¶
Bases: ConnectorError
A schema mapping does not match the external data source.
ConnectorLockedError¶
ConnectorLockedError ¶
Bases: ConnectorError
The target resource is locked by another process.
ConnectorTransientError¶
ConnectorTransientError ¶
Bases: ConnectorError
A transient error (deadlock, timeout) that may succeed on retry.
ConnectorDriverError¶
ConnectorDriverError ¶
Bases: ConnectorError
A required database driver is not installed on the system.
ConnectorDependencyError¶
ConnectorDependencyError ¶
Bases: ConnectorError
A required Python package (extra) is not installed.
Domain errors¶
DomainValidationError¶
DomainValidationError ¶
Bases: MachinaError
A domain entity failed validation.
AssetNotFoundError¶
AssetNotFoundError ¶
Bases: MachinaError
The requested asset was not found in the registry.
Agent / LLM / workflow errors¶
AgentError¶
AgentError ¶
Bases: MachinaError
Error in the agent runtime layer.
LLMError¶
LLMError ¶
Bases: AgentError
Error calling or processing an LLM response.
WorkflowError¶
WorkflowError ¶
Bases: AgentError
Error executing a workflow step.
Sandbox policy¶
SandboxViolationError¶
SandboxViolationError ¶
Bases: ConnectorError
A write operation was blocked because sandbox mode is active.