Errors

This page documents logger-level errors.

These errors describe failures in the logger package itself: context errors and package-level sink configuration errors.

AsyncioLogSink runtime errors are documented separately on the AsyncioLogSink API page.

Error hierarchy

The logger error hierarchy has two main branches:

LoggerError
   |
   +-- LogContextError
   |      |
   |      +-- LogContextResetError
   |      +-- LogContextUnableToLog
   |
   +-- LogSinkConfigurationError
          |
          +-- LogSinkConfigurationConflictError
          +-- LogSinkDescriptorBuildError
          +-- LogSinkCreateError
          +-- LogSinkCloseError
          +-- LogSinkIsInUseError

LoggerError is the common base class for logger-specific errors.

class mvx.common.logger.LoggerError(*, message, details=None, cause=None, reason=None)

Base class for logger-specific errors.

Parameters:

• message (str)

• details (Optional[Mapping[str, Any]])

• cause (Optional[Exception])

• reason (Optional[str])

Context errors

Context errors are raised by LogContext operations.

class mvx.common.logger.LogContextError(*, message, details=None, cause=None, reason=None)

Base class for LogContext errors.

Parameters:

• message (str)

• details (Optional[Mapping[str, Any]])

• cause (Optional[Exception])

• reason (Optional[str])

class mvx.common.logger.LogContextResetError(target)

Raised when a root log context component cannot be reset.

Root contexts have no parent fallback, so mandatory infrastructure such as sink, payload processor, and logging error handling policy cannot be reset.

Create a root-context reset error.

Parameters:

target (str) – component name that cannot be reset.

class mvx.common.logger.LogContextUnableToLog(cause)

Raised when a log context cannot deliver a prepared event.

This error is raised when sink delivery fails and the effective LogErrorHandlingPolicy is RAISE.

Create an unable-to-log error.

Parameters:

cause (Exception) – original sink delivery exception.

Reset errors

LogContextResetError is raised when code tries to reset mandatory root context infrastructure.

Root contexts have no parent fallback, so these components cannot be reset:

log sink
payload processor
logging error handling policy

Child contexts may reset their local overrides and return to inherited behavior.

Delivery errors

LogContextUnableToLog is raised when a prepared event cannot be delivered and the effective context error handling policy is RAISE.

This error describes a logging infrastructure failure, not a domain failure from the code being logged.

Sink configuration errors

Sink configuration errors are raised by package-level sink registration, creation, close, and reset flows.

class mvx.common.logger.LogSinkConfigurationError(message, reason, details=None, cause=None)

Base class for package-level sink configuration errors.

Create a sink configuration error.

Parameters:

• message (str) – error message describing the configuration failure.

• reason (str) – machine-readable reason code.

• details (dict[str, Any] | None) – optional structured error details.

• cause (Exception | None) – optional original exception.

class mvx.common.logger.LogSinkConfigurationConflictError(sink_name, existing_descriptor, requested_descriptor)

Raised when a sink name is already registered with a different descriptor.

The package-level sink registry treats same-name, same-descriptor registration as idempotent. Same-name, different-descriptor registration is a conflict.

Create a sink configuration conflict error.

Parameters:

• sink_name (str) – package-level sink name.

• existing_descriptor (LogSinkDescriptor) – descriptor already registered for this name.

• requested_descriptor (LogSinkDescriptor) – descriptor requested by the new configuration.

class mvx.common.logger.LogSinkDescriptorBuildError(sink_name, sink_class, cause)

Raised when sink descriptor construction fails.

This error wraps an exception raised by sink_cls.build_descriptor(…).

Create a descriptor-build failure error.

Parameters:

• sink_name (str) – package-level sink name.

• sink_class (LogSinkClassProto) – sink class used for configuration.

• cause (Exception) – original descriptor construction exception.

class mvx.common.logger.LogSinkCreateError(sink_name, sink_class, cause)

Raised when sink creation fails.

This error wraps an exception raised by sink_cls.create(…).

Create a sink creation failure error.

Parameters:

• sink_name (str) – package-level sink name.

• sink_class (LogSinkClassProto) – sink class used for configuration.

• cause (Exception) – original sink creation exception.

class mvx.common.logger.LogSinkCloseError(causes)

Raised when one or more package-level sinks cannot be closed.

The error contains structured details for every sink terminator that failed.

Create a sink close failure error.

Parameters:

causes (tuple[tuple[str, Exception], ...]) – sink names and exceptions raised by their terminators.

class mvx.common.logger.LogSinkIsInUseError(sink_name, context_namespaces)

Raised when a package-level sink cannot be closed because it is still in use.

A sink is considered in use when it is locally assigned to one or more registered log contexts.

Create a sink-in-use error.

Parameters:

• sink_name (str) – package-level sink name.

• context_namespaces (tuple[str, ...]) – namespaces of contexts that locally use the sink.

Configuration conflicts

LogSinkConfigurationConflictError is raised when a sink name is already registered with a different descriptor.

The package-level sink registry treats this as idempotent:

same name + same descriptor

and this as a conflict:

same name + different descriptor

Descriptor build failures

LogSinkDescriptorBuildError wraps an exception raised while building a sink descriptor.

This happens before sink creation.

The descriptor step is used to decide whether a registration request is idempotent or conflicting.

Sink creation failures

LogSinkCreateError wraps an exception raised while creating a sink instance and its terminator.

This error means descriptor creation succeeded, but sink construction failed.

Sink close failures

LogSinkCloseError is raised when one or more sink terminators fail while closing sinks.

It can be raised by:

close_log_sink(...)
reset_logger()

The error details contain one entry per failed sink terminator.

Sink-in-use errors

LogSinkIsInUseError is raised when code attempts to close a package-level sink that is still locally assigned to one or more registered contexts.

The sink must be detached from those contexts before it can be closed.

Boundary with operation errors

Logger errors should not be confused with domain errors raised by application code.

For example, if a decorated operation raises RuntimeError, log_invocation may emit a failed outcome and then re-raise the same RuntimeError.

If the logger itself cannot deliver the prepared event, that is a logger infrastructure failure and may surface as LogContextUnableToLog depending on the effective error handling policy.

operation failure
    original domain exception

logger delivery failure
    logger error