Exceptions reference

Scrinium's own exceptions carry the Scrinium prefix and live in Etherna.Scrinium.Core.Exceptions. The configuration family surfaces at engine build (startup), so misconfigurations fail fast rather than corrupting data; the others surface at runtime. This page lists what throws each one.

Startup / configuration

Validation of your maps and references — fix these before the app can start.

Exception	Thrown when
ScriniumDuplicateSchemaIdException	Two schema ids collide across the db context (ids must be unique context-wide; fallback is reserved).
ScriniumDuplicateDiscriminatorException	Two model types share a document discriminator — the _t value, defaulting to the simple type name, so homonymous types in different namespaces collide on it. A shared discriminator can't resolve its model type at read: set a distinct one with BsonClassMap.SetDiscriminator. A discriminator shared only by abstract types is exempt: never being the concrete type of a serialized instance, it is never written nor looked up.
ScriniumAmbiguousRepositoryException	A reference serializer without a declared source finds more than one compatible repository — or only key-incompatible ones — at the nearest hierarchy level (declare its sourceRepository). Also thrown at runtime when resolving the repository of a model type that several repositories handle.
ScriniumInvalidEntityTypeException	A declared source repository doesn't host the reference's model type, or has a different key type. Also thrown at runtime when a model of the wrong type is passed to a repository operation (DeleteAsync, SaveChangesAsync).
ScriniumInvalidIdMemberException	An entity model map (reference configurations included) maps an invalid document id member: one that isn't the implicit IEntityModel<TKey>.Id implementation (the typed id contract and the persisted identity must be the same member), or one that doesn't serialize to a value of a committed type — a composite id, or an object id without a mapped serializer of its own (Domain models).
ScriniumEmbeddedEntityModelException	A member serializes an entity model through its class map instead of a reference serializer — entity models can't embed as full documents (reference configurations included; a custom serializer on the member or type opts out).
ScriniumNotPropagatedReferenceException	A reference id element path contains an unknown document key — a dictionary serialized in document representation — that the dependency updates can't address, so its summaries would go stale, and the NotPropagatedReferences option declares Throw (the default Warn reports each path with a warning instead).

A reference serializer whose source can't be resolved at all fails the build with a plain InvalidOperationException: no compatible repository exists on the context (add one, or declare a cross-context source), or a declared source names a db context type this context doesn't implement and that isn't reachable through exactly one declared child — missing or ambiguous.

Runtime

Exception	Thrown when
ScriniumEntityNotFoundException	FindOneAsync finds no document (use TryFindOneAsync to get null instead).
ScriniumLazyLoadingException	An implicit lazy load runs while the ImplicitLazyLoad option denies them (Throw) — preload with LoadValuesAsync instead.
ScriniumMissingOriginDocumentException	A summary's full load finds no origin document — the referred document doesn't exist on its collection anymore — and its reference declares the Throw missing origin document mode, the strict opt-in (the default Warn degrades the summary with a warning instead). Fix the inconsistency — every repository finds and removes such references, also from the Admin dashboard; see Repositories — or reconsider the mode of that reference.
ScriniumOutdatedModelTypeException	Interacting with a loaded instance whose document changed type after the load — its runtime type can't upgrade; reload the model from its repository.
ScriniumDbMigrationException	A migration execution asked to throw on errors (throwOnErrors: true — the seeding-driven migration is one) completes with errors, or can't resume the db context lock claim its start made; any other execution records the failure on the operation and logs it, without throwing.
ScriniumDbSeedingException	Seeding fails, or another owner held the db context lock for the whole lockWaitTimeout.
ScriniumIndexBuildingException	A custom index definition can't render its keys against the collection serializers. (Server-side index failures during a migration land on the operation — see ScriniumDbMigrationException.)
ScriniumElementPathRenderingException	A reference member's element path can't be rendered (field names or member-map filters), during the dependencies propagation or the missing origin references removal.

From the execution and access layers

These come from the surrounding infrastructure rather than the Scrinium* family:

Exception	Thrown when
ExecutionContextNotFoundException	A serializer modifier is enabled, or an exclusive-access flow starts, with no ambient execution context — open one with InitAsyncLocalContext. Ordinary operations self-create a context and never throw this.
UnauthorizedAccessException	A flow writes a context's collections — or reads them, when the holder locked on read — while another holds exclusive access (e.g. during a migration); or a flow writes a read-only collection — index management included.
TimeoutException	An exclusive-access window can't drain the operations admitted before it opened within the ExclusiveAccessDrainTimeout db context option: the exclusive action never runs beside them, and the engine returns to normal access.
InvalidOperationException	Engine.DbContextLock is read, or a resource lock is asked for, on a read-only context: claiming a lock would write a database this context can only read.
FormatException	An id value serializes to a document or an array, so the operation can't address a document by it — an entity id is always a value (Domain models). TryFindOneAsync reads it as an id matching nothing and returns null instead of throwing.

---

Next: Best practices and pitfalls to avoid the situations that trigger these.