Skip to content

xtr_dependency_injection.exception

Every error this package raises.

All of them derive from :class:DependencyInjectionError, so one except catches anything the kernel can go wrong with, and a narrower one handles a single cause. Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed.

BuilderFrozenError

BuilderFrozenError(operation: str)

Bases: DependencyInjectionError

A definition was changed after compilation; the container would never see it.

Record the operation attempted.

BuilderPhaseError

BuilderPhaseError(operation: str, phase: str)

Bases: DependencyInjectionError

An operation was called outside the phases it belongs to.

scan and autoconfigure only mean something while bundles load: after that, scanning and autoconfiguration have already run.

Record the operation and the phase it was attempted in.

BundleDefinitionError

BundleDefinitionError(bundle: str, reason: str)

Bases: DependencyInjectionError

A bundle is declared in a way the kernel cannot use.

A bad @as_bundle, a class missing it, a reserved name, a bundle or config type that cannot be built with no arguments, or two active bundles claiming one config type.

Record the bundle and what is wrong with it.

CacheFileWriteError

CacheFileWriteError(path: Path)

Bases: DependencyInjectionError

A cache file could not be written; the filesystem's error is its __cause__.

Attributes:

  • path (Path) –

    The file that was to be written.

Record the file that could not be written.

CircularBundleDependencyError

CircularBundleDependencyError(cycle: tuple[str, ...])

Bases: DependencyInjectionError

Bundles depend on each other in a loop: through @required_bundle, or AliasOf.

Record the loop, its first bundle repeated at the end.

ConfigProviderError

ConfigProviderError(provider: str, reason: str)

Bases: DependencyInjectionError

A configuration or parameters provider cannot be used.

Its signature or return is wrong, it was found too late (by a scan a bundle requested while loading), it targets NoConfig, it produced a bad parameter key, or it carries two markers that exclude each other.

Record the provider and what is wrong with it.

ConflictingConfigProvidersError

ConflictingConfigProvidersError(config_type: type, providers: tuple[str, ...])

Bases: DependencyInjectionError

Two base providers of one group replace the same config; neither may silently win.

Record the config type and the competing providers.

ContainerCompilationError

ContainerCompilationError(reason: str)

Bases: DependencyInjectionError

The engine refused to compile the container.

Raised by the compiler when the underlying engine reports the definitions do not form a valid container (e.g. an unresolvable constructor dependency). The original engine error is available via __cause__; any origin notes the compiler attached to it are preserved.

Record the engine's message.

DecoratorSignatureError

DecoratorSignatureError(decorator: str, reason: str)

Bases: DependencyInjectionError

A decorator lacks exactly one AutowireDecorated parameter of the decorated type.

Record the decorator and what is wrong with its signature.

DependencyInjectionError

Bases: Exception

Base class for every error raised by this package.

Catch this to handle anything the kernel can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.

DetachedVariableConflictError

DetachedVariableConflictError(name: str, registered: object, value: object)

Bases: DependencyInjectionError

A context variable already registered to start new connections at another value.

Every kernel in a process shares one registry, so the same variable may be registered again — with the same value, which changes nothing. Two values would leave a new connection's start depending on which came last.

Record the variable and the two values it was registered with.

DuplicateBundleError

DuplicateBundleError(name: str, first: str, second: str)

Bases: DependencyInjectionError

Two bundles, or two entry points, claim one name.

A name identifies a bundle everywhere — in bundle reports, in a config prepend, in kernel.bundles — so it must mean one thing.

Record the name and both claimants.

DuplicateServiceError

DuplicateServiceError(key: tuple[type, Hashable | None], first: Origin, second: Origin)

Bases: DependencyInjectionError

Two definitions claim one key, and neither is allowed to override the other.

The application overrides a bundle silently; two bundles, or two application definitions, never do — unless a bundle calls builder.set_definition on purpose.

Record the key and the origins of both definitions.

EnvPlaceholderError

EnvPlaceholderError(expression: str, reason: str)

Bases: DependencyInjectionError

An env(...) placeholder was used as if it were already a value.

A placeholder stands for a variable read when the service needing it is built. Deciding the container's structure with one — testing it in an if, embedding a non-scalar in a string, naming an unknown processor prefix — cannot work, because the value does not exist yet.

Attributes:

  • expression (str) –

    The placeholder's expression, e.g. "int:PORT".

  • reason (str) –

    Why it cannot be used there.

Record the expression and why it cannot be used there.

FastapiIntegrationError

FastapiIntegrationError(reason: str)

Bases: DependencyInjectionError

The web integration cannot serve a request from the container.

Raised when a resolver runs with no attached kernel or no open request scope, and when a second kernel is attached to an application one already serves.

Attributes:

  • reason (str) –

    What the integration is missing.

Record what the integration is missing.

InvalidArgumentError

InvalidArgumentError(reason: str)

Bases: DependencyInjectionError, ValueError

A value this package was given cannot be used as it is.

Also a :class:ValueError, so a caller can catch either this package's errors as a whole or the built-in.

Attributes:

  • reason (str) –

    What is wrong with the value.

Record what is wrong with the value.

InvalidArgumentTypeError

InvalidArgumentTypeError(reason: str)

Bases: DependencyInjectionError, TypeError

Something this package was given is not of a kind it accepts.

Also a :class:TypeError, so a caller can catch either this package's errors as a whole or the built-in.

Attributes:

  • reason (str) –

    What was expected, and what was given.

Record what was expected, and what was given.

InvalidDefinitionError

InvalidDefinitionError(key: tuple[type, Hashable | None], reason: str)

Bases: DependencyInjectionError

A compiler pass found a definition or alias inconsistent with itself.

Raised before the engine sees the container: a provider that does not match its kind or key, an unknown lifetime, a kernel.reset tag naming no method, an alias whose target does not implement it.

Record the key and why its definition is invalid.

InvalidEnvironmentError

InvalidEnvironmentError(env: str, allowed: tuple[str, ...])

Bases: DependencyInjectionError

The environment is not one of the kernel's allowed_envs.

Record the environment asked for and those allowed.

InvalidEnvironmentVariableError

InvalidEnvironmentVariableError(name: str, cast: str | Callable[..., object], value: str)

Bases: DependencyInjectionError

A processor or cast refused a variable's value.

The error that refused it is __cause__ only when its own message says nothing about the value: one that quotes the value — or the path the value names — is dropped, so a logged traceback cannot carry a secret.

Attributes:

  • name (str) –

    The variable, or the expression being processed.

  • cast (str | Callable[..., object]) –

    The processor prefix ("int", "json"…) or the callable that refused it.

  • value (str) –

    The value refused. Kept out of the message, which is logged: the variable may hold a secret.

Record the variable, the conversion, and the value that failed it.

InvalidParameterTypeError

InvalidParameterTypeError(name: str, type_name: str, value: str)

Bases: DependencyInjectionError

A %name% reference inside a longer string names a value that cannot be embedded.

Attributes:

  • name (str) –

    The parameter referenced.

  • type_name (str) –

    The type of its value.

  • value (str) –

    The string it was embedded in.

Record the parameter, its type, and the string it was embedded in.

KernelAlreadyBootedError

KernelAlreadyBootedError()

Bases: DependencyInjectionError

boot() was called a second time on one compiled kernel.

Boot hooks run once per container; build the kernel again for another.

Compose the message.

KernelShutDownError

KernelShutDownError()

Bases: DependencyInjectionError

The kernel whose container is asked for a service has shut down.

Its singletons were closed when it did, so handing one out — or building a new one nothing would ever close — is refused.

Compose the message.

MissingBundleError

MissingBundleError(name: str, required_by: str | None, reason: str | None)

Bases: DependencyInjectionError

A bundle that is required, or listed explicitly, is absent or was skipped.

Record the missing bundle, who needs it, and why it is missing, when known.

MissingEnvironmentVariableError

MissingEnvironmentVariableError(name: str)

Bases: DependencyInjectionError

An environment variable a service needs is not set, and has no default.

Record the variable's name.

ParameterCircularReferenceError

ParameterCircularReferenceError(path: tuple[str, ...])

Bases: DependencyInjectionError

A %name% reference loops back on itself.

Attributes:

  • path (tuple[str, ...]) –

    Every parameter of the loop, ending with the first one again.

Record the path of the loop.

ParameterConflictError

ParameterConflictError(path: tuple[str, ...], first: str, second: str)

Bases: DependencyInjectionError

A parameter leaf is set by two sources; parameters merge, they do not override.

Record the parameter's path and the two sources setting it.

ParameterNotFoundError

ParameterNotFoundError(name: str)

Bases: DependencyInjectionError, LookupError

No parameter is set for this dotted name.

Raised by :class:ContainerInterface.get_parameter when :meth:has_parameter is False for the same name, so callers can catch a LookupError without coupling to this package.

Record the parameter name that is not defined.

ResourceImportError

ResourceImportError(module: str)

Bases: DependencyInjectionError

A scanned module failed to import; the original error is its __cause__.

Record the module that failed.

ScopeTeardownTimeoutError

ScopeTeardownTimeoutError(timeout: float)

Bases: DependencyInjectionError

Closing a unit's scoped services took longer than it is given.

Each teardown is the code after yield in a scoped factory; one that never returns — a connection that hangs on close — would otherwise hold the unit, and whatever waits for it, forever.

Record how long the teardown was given.

ServiceCircularReferenceError

ServiceCircularReferenceError(key: tuple[type, Hashable | None], path: tuple[tuple[type, Hashable | None], ...])

Bases: DependencyInjectionError

An alias chain loops back on itself.

Attributes:

Record the key and the path of the loop.

ServiceNotFoundError

ServiceNotFoundError(key: tuple[type, Hashable | None])

Bases: DependencyInjectionError, LookupError

No service is registered under this (type, qualifier) key.

Raised by :class:ContainerInterface.get when :meth:has is False for the same arguments, so callers can catch a LookupError without coupling to this package.

Record the key nothing was registered for.

ServiceOrderError

ServiceOrderError(reason: str)

Bases: DependencyInjectionError

The before/after constraints on tagged services cannot be satisfied.

Raised by :func:sort_with_priorities when a constraint contradicts an explicit priority, when the bounds derived from unprioritised items are unsatisfiable, or when the constraints form a cycle. reason is the sorter's message, verbatim.

Record the sorter's message describing what is wrong.

ServiceResolutionError

ServiceResolutionError(key: tuple[type, Hashable | None], reason: str, /, *, advice: str | None = None)

Bases: DependencyInjectionError

The engine failed to build an already-registered service.

Raised by :class:ContainerInterface.get when the service is registered (:meth:has is true) but the engine could not build it. :attr:reason is the engine's own message, repeated in this error's message; the original engine error is available via __cause__. advice names how this package resolves the service when the engine failed for a reason a caller can act on (a scoped or transient service requested without a scope).

Record the key whose resolution failed and the engine's message.

UnitOfWorkClosedError

UnitOfWorkClosedError()

Bases: DependencyInjectionError

The unit of work a container or a bound call resolves from has exited.

Its scoped services were released when it did, so handing one out — or building one nothing would ever release — is refused. Work that outlives the unit it was started in, a task it spawned, opens one of its own with unit_of_work(container, join=False).

Compose the message.

UnitReadDuringSingletonBuildError

UnitReadDuringSingletonBuildError(read: str)

Bases: DependencyInjectionError

A singleton's factory read what belongs to one unit of work.

A singleton is built once and kept by every unit after, so it would hold on to whichever unit — whichever request — happened to build it. Raised in a kernel built in debug mode only; read it where it is used instead, or make the service scoped.

Record what was read.

UnknownConfigTypeError

UnknownConfigTypeError(provider: str, config_type: type, inactive_bundle: str | None)

Bases: DependencyInjectionError

No active bundle owns the config type a provider returns.

inactive_bundle names the bundle that owns it but is excluded or disabled in this environment — usually the real cause.

Record the provider, its config type, and the inactive owner, if any.

UnknownEnvironmentFolderError

UnknownEnvironmentFolderError(folder: str, allowed: tuple[str, ...])

Bases: DependencyInjectionError

A subpackage of config.packages or config.routes is not an allowed environment.

Every such subpackage is an environment folder, imported only in the environment it is named after; with allowed_envs set, a name outside them is a folder no build would ever import — most often a typo.

Attributes:

  • folder (str) –

    The folder's dotted module name.

  • allowed (tuple[str, ...]) –

    The environments the kernel allows.

Record the folder and the environments it could have been named after.

UnknownLocatorKeyError

UnknownLocatorKeyError(key: Hashable, known: tuple[Hashable, ...])

Bases: DependencyInjectionError, LookupError

A service locator was asked for a key it does not hold.

Record the key asked for and those the locator holds.

UnknownServiceError

UnknownServiceError(key: tuple[type, Hashable | None], operation: str)

Bases: DependencyInjectionError

replace, remove, decorate or resettable target a key nothing defines.

Record the key and the operation that needed it.