Errors

• Start here: Configuration
• The contract: Configuration internals

Every grelmicro error subclasses GrelmicroError, so one except catches any of them. A bad configuration value always raises SettingsValidationError, whichever pattern or component you built.

grelmicro

grelmicro is a lightweight framework/toolkit which is ideal for building async microservices in Python.

GrelmicroError

Bases: Exception

Base grelmicro error.

SettingsValidationError

SettingsValidationError(error: ValidationError | str)

Bases: GrelmicroError, ValueError

Raised when a configuration value fails validation.

Every grelmicro class raises this one error, whichever pattern or component it is, so one except covers the whole library. A config class you build yourself, such as RetryConfig(...), raises pydantic's ValidationError like any pydantic model.

Subclasses ValueError, which pydantic.ValidationError also is, so an except ValueError catches either.

Pydantic ValidationError messages already describe the failure shape ("Input should be a valid string", "Input should be greater than 0", ...) so the raw input is intentionally omitted from the rendered error. Settings often originate from environment variables that may carry credentials (DSNs, tokens), and echoing the offending value into a log line would leak them.

Initialize the error.

AdmissionError

Bases: GrelmicroError

Raised when a gatekeeping primitive refuses a call.

The shared base for every "turned away" rejection: a rate limiter over budget (RateLimitExceededError), a full bulkhead (BulkheadFullError), an open circuit breaker (CircuitBreakerError), or a non-blocking lock acquire that would block (WouldBlockError). Catch AdmissionError to handle any admission rejection with one except.

BackendScopeError

Bases: GrelmicroError, RuntimeError

Raised when a backend does not reach as far as its component requires.

A Lock on a memory backend excludes nothing once a second replica runs. So in staging and production, a component bound to a backend whose scope falls short of what it requires refuses to open, before the first connection is made. Wire a backend that reaches far enough, or pass requires= to declare the reach you meant.

micro.check_backends() raises the same error from a test, so the wiring is answered for before a pod answers for it.

Carries the backend-scope code, the same one BackendScopeWarning carries when no tier is declared.

code class-attribute

code: str = 'backend-scope'

DependencyNotFoundError

DependencyNotFoundError(*, module: str)

Bases: GrelmicroError, ImportError

Dependency Not Found Error.

Initialize the error.

MultipleActiveAppsError

MultipleActiveAppsError()

Bases: GrelmicroError, RuntimeError

Raised when a second Grelmicro app is opened while one is active.

Components such as Log and Trace configure process-global state (the stdlib root logger, the OpenTelemetry tracer provider) and restore it in reverse order on exit. Two overlapping app lifecycles in the same process would restore that state out of order and clobber each other, so a second concurrent app is blocked by default. Run apps one at a time, or pass Grelmicro(allow_multiple=True) if you are sure no two active apps configure the same global state.

Initialize the error.

OutOfContextError

OutOfContextError(
    cls: object, method_name: str | None = None
)

Bases: GrelmicroError, RuntimeError

Outside Context Error.

Raised when a method is called outside of the context manager.

Initialize the error.

Pass a context object and a method name for the default message, or a single ready-made message string.

AdapterNotRegisteredError

AdapterNotRegisteredError(
    kind: str, short_name: str, available: list[str]
)

Bases: GrelmicroError, LookupError

Raised when no Adapter is registered under a short name for a kind.

Short names resolve against the grelmicro.{kind}.adapters entry-point group. A miss usually means the package that ships the Adapter is not installed, or the name is misspelled.

Initialize the error.

ProviderNotRegisteredError

ProviderNotRegisteredError(
    short_name: str, available: list[str]
)

Bases: GrelmicroError, LookupError

Raised when no Provider is registered under a requested short name.

Short names resolve against the grelmicro.providers entry-point group. A miss usually means the package that ships the Provider is not installed, or the name is misspelled.

Initialize the error.

GrelmicroConfigWarning

Bases: UserWarning

Warned when configuration is set in a way that will not take effect.

A category of its own so it can be filtered precisely, without silencing every UserWarning and without matching on the message text:

filterwarnings = ["error", "ignore::grelmicro.GrelmicroConfigWarning"]

Each diagnostic also has its own subclass, so one can be silenced without silencing the rest. The code attribute is the diagnostic's stable identifier, matching the section at /diagnostics/#{code}.

code class-attribute

code: str = ''

Stable diagnostic code, empty on the base category.

EnvLoadOffWarning

Bases: GrelmicroConfigWarning

A GREL_* variable is set but GREL_ENV_LOAD is off.

code class-attribute

code: str = 'env-load-off'

BackendScopeWarning

Bases: GrelmicroConfigWarning

A bound backend reaches less far than its component requires.

The same problem raises BackendScopeError in staging and production. Both carry the backend-scope code.

code class-attribute

code: str = 'backend-scope'

AmbientBindingWarning

Bases: GrelmicroConfigWarning

Ambient components are registered but the binding middleware is missing.

The same problem raises AmbientBindingError under Grelmicro(strict=True). Both carry the ambient-binding code.

code class-attribute

code: str = 'ambient-binding'

SentinelPasswordWarning

Bases: GrelmicroConfigWarning

A Sentinel password is set but the URL scheme cannot apply it.

code class-attribute

code: str = 'sentinel-password'

UnknownEnvironmentWarning

Bases: GrelmicroConfigWarning

GREL_ENVIRONMENT names no tier grelmicro knows.

code class-attribute

code: str = 'unknown-environment'