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.
ConnectorUnsupportedFilterError¶
ConnectorUnsupportedFilterError ¶
Bases: ConnectorError
The connector cannot apply a filter it was given, so it refuses the read.
Raised before any request to the backend, in place of dropping the filter
(which would pass the unfiltered result off as the filtered one) or
answering [] (which would read as "nothing matches"). The message names
the filter and why it cannot be applied, never the caller's value. Catch it
apart from other connector errors when the refusal is an expected outcome
rather than a failure, e.g. to retry by a filter the backend does support.
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.