Only the exception classes re-exported by @event-nest/core are listed as public API. Catch the narrow exception you can recover from; let invalid model/configuration errors fail fast.
AggregateClassNotSnapshotAwareException
Trigger
Snapshot lookup or creation needs snapshot revision metadata, but the aggregate class has none.
Typical cause
The aggregate can match a snapshot path while @AggregateRootConfig omits snapshotRevision, or the metadata is not numeric.
Response
Add a numeric snapshotRevision and implement SnapshotAware, or exclude the aggregate from the configured snapshot strategy.
AggregateInstanceNotSnapshotAwareException
Trigger
A snapshot is applied or a matching strategy requests creation, but the instance does not expose callable toSnapshot and applySnapshot methods.
Typical cause
SnapshotAware was implemented incompletely, a method was renamed, or a snapshot was passed to a non-snapshot aggregate.
Response
Implement both methods and add snapshotRevision metadata, or do not pass/configure snapshots for this aggregate.
EventConcurrencyException
Trigger
The version expected by a save differs from the persisted aggregate version.
Typical cause
Another writer committed first, a stale instance was reused, or a snapshot-only load failed to pass aggregateRootVersion into reconstitute.
Response
Reload and re-run the command under domain-safe retry rules. Snapshot factories must forward the version returned by findWithSnapshot.
The exception exposes its information through its message only: Concurrency issue for aggregate <id>. Expected <expected>. Stored <database>.
EventNameConflictException
Trigger
@DomainEvent registers a canonical name or alias already present in the process, including duplicates within one registration.
Typical cause
Two event classes share storage identity or an alias collides with another canonical name/alias.
Response
Assign globally unique names and aliases. Do not remove an old alias until its persisted rows have been migrated or retired.
MissingAggregateRootNameException
Trigger
Publishing, reading, or snapshot lookup cannot resolve aggregate-name metadata.
Typical cause
The aggregate class lacks @AggregateRootConfig (or the deprecated @AggregateRootName), or the wrong class was supplied to a read.
Response
Decorate the aggregate with @AggregateRootConfig and its name property, then preserve the durable name used by existing events.
The current exception text still mentions @AggregateRootName; use @AggregateRootConfig, because the former is deprecated.
SnapshotRevisionMismatchException
Trigger
findWithSnapshot finds a stored snapshot whose revision differs from the aggregate class revision.
Typical cause
The snapshot payload format/revision changed or deployments disagree on aggregate metadata.
Response
Replay the complete event stream and write a new compatible snapshot. AggregateRepository.load performs this fallback automatically; direct findWithSnapshot callers must handle it.
SubscriptionException
Trigger
An awaited subscription rejects after events have been persisted.
Typical cause
An isAsync: false handler failed; in default sequential dispatch, a mixed batch that contains a synchronous subscription waits for the entire sequence, so any handler in that sequence can surface this exception.
Response
Inspect caughtError, eventClassName, and eventId. Repair/retry the projection or side effect idempotently; do not commit the domain events again.
SubscriptionException has public caughtError, eventClassName, and eventId getters. AggregateRoot.commit() clears its uncommitted events when this exception is caught because persistence already happened.
UnknownEventException
Trigger
AggregateRoot.reconstitute finds an unregistered stored event name or no @ApplyEvent method for its resolved class.
Typical cause
An event class was not imported/registered, a persisted name changed without an alias, or the aggregate lacks the matching replay method.
Response
Ensure startup imports every @DomainEvent class, preserve old names as aliases, and add an @ApplyEvent handler for every event in that aggregate stream.
Its message separates Unregistered persisted names from registered names with a Missing apply method.
Internal and generic errors
Some actionable failures use classes that exist in source but are not exported by the public barrel. Do not deep-import them:
Appending an undecorated event throws internal UnregisteredEventException.
A custom event store returning the wrong number of generated IDs can trigger internal IdGenerationException.
A custom store that does not return a saved event/version for every publication can trigger internal UnknownEventVersionException.
Configuration and strategy validation also uses plain Error, including incomplete snapshot option pairs, invalid strategy counts/empty composites, invalid SQL Server identifiers, mutually exclusive SQL Server port/instanceName, and invalid aggregateRootVersion passed to reconstitute.
