XC_VM/docs/en/development/exception-hierarchy.md

Exception Hierarchy

All XC_VM exceptions extend XcVmException so callers can catch the entire tree with one catch block or target a specific subsystem.

---

Tree

\Exception
└── XcVmException
    ├── Container
    │   └── ContainerException          (PSR-11 ContainerExceptionInterface)
    │       ├── CircularDependencyException
    │       ├── ServiceCreationException
    │       └── NotFoundException       (PSR-11 NotFoundExceptionInterface)
    └── Module
        └── ModuleException
            ├── ModuleNotFoundException
            ├── ModuleLoadException
            ├── ModuleManifestException
            └── ModuleCycleException

---

Container exceptions

Class	When thrown
ContainerException	Base for all container failures
CircularDependencyException	A service's factory graph contains a cycle
ServiceCreationException	Factory callable threw while creating a service
NotFoundException	get($id) called for an unregistered service

NotFoundException implements both PSR-11 interfaces so the container is compliant:

try {
    $service = $container->get('unknown');
} catch (NotFoundException $e) {
    // PSR-11 NotFoundExceptionInterface
}

---

Module exceptions

Class	When thrown
ModuleException	Base for all module failures
ModuleNotFoundException	Required dependency module is missing
ModuleLoadException	Module file cannot be loaded or class not found
ModuleManifestException	module.json is missing, malformed, or fails validation
ModuleCycleException	Dependency graph has a cycle

---

Catching by subsystem

// Catch any XC_VM exception
try {
    $loader->loadAll();
} catch (XcVmException $e) {
    logger()->error($e->getMessage());
}

// Catch only module-related failures
try {
    $loader->loadAll();
} catch (ModuleException $e) {
    // ModuleNotFoundException | ModuleLoadException | ...
}

// Catch container-specific failures
try {
    $container->get('missing');
} catch (ContainerException $e) {
    // CircularDependencyException | NotFoundException | ...
}

---

Location

src/Core/Exception/
├── XcVmException.php
├── Container/
│   ├── ContainerException.php
│   ├── CircularDependencyException.php
│   ├── ServiceCreationException.php
│   └── NotFoundException.php
└── Module/
    ├── ModuleException.php
    ├── ModuleNotFoundException.php
    ├── ModuleLoadException.php
    ├── ModuleManifestException.php
    └── ModuleCycleException.php

Related files

File	Role
src/Core/Exception/	Exception base classes and the project hierarchy