Skip to main content

Errors

Every exception of crdt_lf extends CrdtException, which carries a message. Catch CrdtException to handle them all, or one subclass to handle one case.

try {
doc.applyChange(change);
} on CausallyNotReadyException {
// The change depends on changes this document does not have yet.
pending.add(change);
} on CrdtException catch (error) {
log(error.message);
}

Errors you can expect​

These come from normal use. Each one says what to fix in the calling code, or what to wait for.

ExceptionWhenWhat to do
CausallyNotReadyExceptionapplyChange gets a change whose dependencies the document does not haveapply the missing changes first, or use importChanges (see below)
HandlerAlreadyRegisteredExceptiona handler constructor runs for an id that is already open, or doc.handler(spec, id) finds the id open as another kindopen a handler once and keep it, or use doc.handler, which returns the open one (Handlers)
HandlerDeletedExceptiona write to, or an open of, a handler that was deleted with deleteHandler; it carries the handlerIdcheck doc.isDeleted(id) before you open the id again
DocumentDisposedExceptionany call on a document after dispose()stop using the document, and the handlers built on it, once it is disposed
ReadOnlyDocumentExceptiona write on the read-only copy that toTimeTravel() returnswrite on the live document, not on the history copy (History)
ConcurrentSnapshotExceptionmergeSnapshot (or import with merge: true) gets a snapshot of a concurrent history that holds the same handler with different bytes; it carries currentId and incomingIdthe document is left as it was. Between two concurrent histories, exchange changes rather than snapshots (Snapshots)
UnknownOperationKindExceptiona change for one of your handlers carries an operation kind this build cannot decode: it comes from a newer peer. It carries handlerType, handlerId and kindupdate the app. The sync layer can refuse such peers before they send data (Versions and compatibility)

importChanges does not throw for a single change. It sorts the changes, applies the ones it can, and skips the others, including the ones that are not causally ready. Its return value is the number of changes it applied. That is why a peer can send everything it has: what is missing now is applied when the changes it depends on arrive.

Errors that mean corrupted data​

ChangesCycleException, MissingDependencyException and DuplicateNodeException protect the change graph. Changes made by crdt_lf never trigger them: they mean that the bytes were changed or built by hand.

Errors that are not CrdtException​

  • FormatException: bytes that cannot be decoded. A Change or a Snapshot of an unknown format, or a handler blob outside the versions this build reads (see Binary format).
  • ArgumentError, StateError, UnsupportedError: a call that is wrong whatever the data, as in the rest of Dart. For example a handler opened under the reserved id of the delete registry, or a handler that CRDTUndoManager cannot track.