Exception Handling and Error Mapping
Relevant source files
The following files were used as context for generating this wiki page:
The opsmill.infrahub collection uses a centralized system to map Infrahub SDK exceptions to descriptive Ansible error messages. This mechanism ensures that technical SDK failures translate into actionable information for automation engineers. All API access mediated through the InfrahubclientWrapper employs this mapping to maintain consistent error reporting across modules and action plugins.
Sources: dev/constitution.md: Principle IV, plugins/module_utils/exception.py
Architecture and Components
Exception handling relies on a decorator pattern that intercepts calls to the Infrahub SDK. The handle_infrahub_exceptions_decorator serves as the primary gateway for catching SDK-specific exceptions and re-raising them as formatted strings or AnsibleError instances.
The Decorator Pattern
The collection applies the handle_infrahub_exceptions_decorator to methods within the InfrahubclientWrapper and specific module utilities. When an SDK method throws a recognized exception, the decorator catches it, extracts the relevant error details, and provides a clear message to the Ansible controller.
Sources: plugins/module_utils/exception.py, dev/knowledge/plugin-patterns.md: Error Handling
Data Flow for Exceptions
The following diagram illustrates how an error propagates from the Infrahub server through the SDK and into the Ansible environment.
The diagram shows the sequence of exception handling where the decorator acts as the translation layer between the raw SDK exceptions and the Ansible reporting mechanism.
Sources: plugins/module_utils/infrahub_utils.py, plugins/module_utils/exception.py
Error Mapping Logic
The mapping logic distinguishes between different types of failures, such as schema mismatches, network issues, and GraphQL validation errors.
Supported Exception Mappings
The collection maps specific infrahub_sdk exceptions to standardized error messages as defined in plugins/module_utils/exception.py.
| SDK Exception | Resulting Ansible Error Message |
|---|---|
GraphQLError | Concatenated list of errors from the GraphQL response |
SchemaNotFoundError | "Schema '{kind}' not found in Infrahub" |
BranchNotFoundError | "Branch '{branch}' not found in Infrahub" |
ServerNotReachableError | "Infrahub server at {address} is not reachable" |
ServerNotResponsiveError | "Infrahub server at {address} is not responding" |
Exception (Generic) | "An unexpected error occurred: {error_details}" |
Sources: plugins/module_utils/exception.py, dev/knowledge/plugin-patterns.md: Error Handling
GraphQL Error Processing
When a GraphQLError occurs, the system does not simply return a generic failure. It iterates through the errors attribute of the exception to extract individual error messages. This process ensures that multiple validation failures in a single GraphQL request are all reported to the user.
Sources: dev/knowledge/plugin-patterns.md: Error Handling, plugins/module_utils/exception.py
Implementation in Plugins
Plugins implement error handling differently depending on their pattern (Module Utils vs. Action Plugin).
Action Plugin Implementation
Action plugins check for the presence of the SDK using the HAS_INFRAHUBCLIENT flag. If the SDK is missing, they raise an AnsibleError immediately. During execution, they wrap SDK client calls in try/except blocks or rely on the InfrahubclientWrapper which is decorated with error handling logic.
The sequence diagram shows the internal call flow when an API call fails and how the decorator transforms the SDK exception before it reaches the action plugin.
Sources: dev/guides/creating-a-module.md: Step 2a, plugins/module_utils/exception.py
Module Utils Implementation
Modules using the InfrahubModule pattern benefit from inherited error handling. Methods like _ensure_object_exists and _ensure_object_absent use the decorated wrapper to perform "Fetch-compare-act" cycles. If an API call fails during these cycles, the decorated wrapper ensures the module fails with a descriptive message rather than a Python traceback.
Sources: dev/constitution.md: Principle III, plugins/module_utils/infrahub_utils.py
Summary of Key Files
| File Path | Role in Exception Handling |
|---|---|
plugins/module_utils/exception.py | Contains the handle_infrahub_exceptions_decorator and error mapping logic. |
plugins/module_utils/infrahub_utils.py | Implements the InfrahubclientWrapper which uses the exception decorator. |
dev/knowledge/plugin-patterns.md | Documents the standard error handling patterns for developers. |
dev/constitution.md | Defines the requirement for centralized API access and exception mapping. |
Sources: AGENTS.md: Key Source Locations, plugins/AGENTS.md: Key Files
Centralized exception handling and error mapping provide a robust layer of abstraction over the Infrahub SDK. By converting low-level API and network errors into readable Ansible messages, the collection improves the debuggability and reliability of infrastructure automation.