Cindel Error Reference: Causes and Recovery Actions

CindelOpenError

CindelOpenError is thrown when the database backend cannot be opened. You will encounter this error at startup, inside your Cindel.open(...) call, never during normal query or write operations.Common causes

The directory path does not exist or is invalid
The application does not have write permission for that directory
A required platform dependency is missing
On Web: the browser does not support the required storage features (OPFS/SQLite Web), private-browsing mode is active, or the storage quota has been exceeded

RecoveryCheck that the target directory exists and is writable before calling open. On Web, detect storage unavailability early and show a graceful message rather than letting the error propagate silently.

try {
  final db = await Cindel.open(
    directory: directory.path,
    schemas: [UserSchema],
  );
} on CindelOpenError catch (e) {
  // Storage is unavailable — inform the user and abort startup.
  print('Cannot open database: $e');
  showStorageUnavailableMessage();
}

CindelSchemaError

CindelSchemaError is thrown when the schemas you pass at open time don’t match the metadata already stored on disk. Like CindelOpenError, this surfaces during Cindel.open(...).Common causes

A required schema is missing from the schemas: list
You changed your data model but forgot to re-run build_runner, so the generated code is stale
Stored data was written with a different schema version and no migration plan was provided

RecoveryMake sure every schema your database uses is listed in schemas:. After any model change, re-run code generation before opening the database. When stored data must be rewritten to match a new model shape, provide a CindelMigrationPlan.

try {
  final db = await Cindel.open(
    directory: directory.path,
    schemas: [UserSchema, ProjectSchema],
  );
} on CindelSchemaError catch (e) {
  // Schema registration or compatibility failure — check for missing
  // schemas, stale generated code, or a missing migration plan.
  showDataUpgradeFailedMessage();
}

CindelDatabaseClosedError

CindelDatabaseClosedError is thrown when code attempts to use a database instance after close() has already been called on it.Common causes

Holding a reference to a database and using it after the owning component has already shut down
Calling close() then reusing the same handle instead of reopening

RecoveryMake ownership clear: the component that opens the database decides when it is closed. Avoid sharing a closed database handle. If you need the database again after closing, open a fresh instance.

await db.close();

// ❌ This throws CindelDatabaseClosedError:
await db.users.all().findAll();

CindelTransactionError

CindelTransactionError is thrown when an invalid transaction operation is attempted at runtime.Common causes

Calling a write operation (e.g. put, delete) inside a readTxn callback
Starting nested explicit write transactions
Using a transaction object after it is already in an invalid or closed state

RecoveryThis error almost always indicates a structural problem in your code rather than a user-recoverable condition. Use readTxn for read-only work and writeTxn for writes, and keep them separate. If you see this error, restructure the offending code path — don’t catch and suppress it.

// ❌ This throws CindelTransactionError:
await db.readTxn(() async {
  await db.todos.put(todo); // Write inside a read transaction.
});

// ✅ Correct:
await db.writeTxn(() async {
  await db.todos.put(todo);
});

CindelQueryError

CindelQueryError is thrown when a query shape is invalid or unsupported at runtime.Common causes

Using a property aggregate (e.g. average()) against a field that holds non-numeric values
Applying an unsupported query update shape
Composing query helpers in a way that produces an invalid query at runtime

RecoveryUse the generated typed where() and filter() helpers — they are shaped to match your model’s actual field types. When using property aggregates, make sure the target field is numeric.

try {
  final average = await db.todos
      .all()
      .titleProperty()
      .average();
} on CindelQueryError catch (e) {
  // The aggregate requires numeric values — check the field type.
  print('Query error: $e');
}

CindelUniqueIndexError

CindelUniqueIndexError is thrown when an insert or update would violate a unique index — for example, storing two accounts with the same email address.RecoveryCatch this error at the call site where you perform the write and surface a user-friendly message. This is the intended recovery path for natural-key conflicts such as email addresses, usernames, SKUs, or slugs.

try {
  await db.writeTxn(() => db.accounts.put(account));
} on CindelUniqueIndexError {
  showDuplicateUsernameMessage();
}

If you want duplicate writes to silently replace the existing record instead of failing, annotate the field with @Index(unique: true, replace: true) and use the generated putBy… helper rather than catching this error:

@collection
class Account {
  // Duplicate emails silently overwrite the existing record.
  @Index(unique: true, replace: true)
  late String email;
  // ...
}

// No exception — the existing account is replaced:
await db.writeTxn(() => db.accounts.putByEmail(account));

CindelNativeError

CindelNativeError is thrown when Cindel receives invalid or unexpected native data, or when a native-facing operation returns a result it cannot interpret.RecoveryThis error is not a user-recoverable condition — it indicates a bug or data corruption. Do not catch it to continue silently. Instead, log the error with full context (operation name, relevant IDs, stack trace) and report it so you can investigate and fix the root cause.

try {
  final count = await db.todos.all().count();
} on CindelNativeError catch (error, stackTrace) {
  // Log and report — this is unexpected and needs investigation.
  reportError(error, stackTrace);
}

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel Error Reference: Causes and Recovery Actions

General Handling Strategy

​General Handling Strategy

General Handling Strategy