Errors & Troubleshooting — Aquilia Documentation
Comprehensive guide and documentation for Errors & Troubleshooting in the Aquilia framework. View API reference, examples, and implementation patterns.
Dependency Injection / Errors & Troubleshooting Errors, Faults & Troubleshooting Every DI failure raises a structured fault, not a bare exception. This page is the complete taxonomy — what each error means, when it fires, and how to fix it. The Fault Hierarchy All DI errors descend from DIFault (domain DI, severity ERROR, non-retryable, non-public). Registration/graph errors live in aquilia.di.errors and subclass DIError; runtime resolution failures raise DIResolutionFault. Because they are faults, the Fault Engine renders them as structured responses automatically. Fault └── DIFault (code varies; domain=DI) ├── DIError ("DI_ERROR") │ ├── ProviderNotFoundError ("PROVIDER_NOT_FOUND") │ ├── DependencyCycleError ("DEPENDENCY_CYCLE") │ ├── ScopeViolationError ("SCOPE_VIOLATION") │ ├── AmbiguousProviderError ("AMBIGUOUS_PROVIDER") │ ├── ManifestValidationError ("MANIFEST_VALIDATION_FAILED") │ ├── CrossAppDependencyError ("CROSS_APP_DEPENDENCY") │ ├── CircularDependencyError ("CIRCULAR_DEPENDENCY") │ └── MissingDependencyError ("MISSING_DEPENDENCY") ├── DIResolutionFault ("DI_RESOLUTION_FAILED") └── DIConfigFault ("DI_CONFIG_INVALID") Exported from aquilia.di: DIError, ProviderNotFoundError, DependencyCycleError, ScopeViolationError, AmbiguousProviderError. The graph-build errors (MissingDependencyError, CircularDependencyError, CrossAppDependencyError, ManifestValidationError) exist in aquilia.di.errors but aren't re-exported — import them from there if you catch them directly. Error Catalog , , , , , , , , , When: Fix: ))} Boot-Time Registration Faults The runtime raises structured DIFaults while wiring services from manifests: Code Cause Behavior ))} Catching DI Faults from aquilia.di import ( ProviderNotFoundError, ScopeViolationError, DependencyCycleError, DIError, ) try: svc = await container.resolve_async(SomeService) except ProviderNotFoundError as e: log.error("Missing provider: token=%s candidates=%s", e.token, e.candidates) except ScopeViolationError as e: log.error("Captive dep: %s(%s) -> %s(%s)", e.provider_token, e.provider_scope, e.consumer_token, e.consumer_scope) except DIError as e: # catch-all for the DI domain log.error("DI failure [%s]: %s", e.code, e.message) Troubleshooting Playbook ))} Validate Before You Ship Catch DI misconfiguration in CI, before it reaches production: # Fail the build on cycles, missing providers, undeclared cross-app deps aq di-check --settings workspace.py --verbose # Visualize the graph for review aq di-graph --settings workspace.py --out di-graph.dot # Inspect the resolution tree from a root aq di-tree --settings workspace.py --root modules.api.services:ApiService Patterns & Recipes Models )
Go to Homepage