Find the failing layer¶

Recognized provider failures are exposed as DormDatabaseException. Validation and unsupported-operation errors can still be ordinary Dart or provider errors. The first useful step is to identify when the failure occurs.

Check project setup first¶

Run commands from the directory that owns the application or package:

dart pub get
dart analyze

For a pure Dart application, use dart run and dart test. A Flutter/Firebase application uses the Flutter toolchain and must initialize Firebase before constructing its dORM engine. The engine pages contain the backend-specific startup sequence:

• Run in-memory
• Run with BLoC
• Run with Firebase
• Run with MySQL
• Run with PostgreSQL
• Run with MongoDB
• Run with HTTP/JSON
• Run with SQLite

Separate generation from runtime¶

If the failure occurs during build_runner, follow Fix code generation problems. A generator failure happens before a repository call and cannot be fixed by changing the engine connection.

If generated files exist but the analyzer reports missing or incompatible types, regenerate before changing application code:

dart run build_runner build --delete-conflicting-outputs
dart analyze

Check the repository precondition¶

Missing records are represented by the result type rather than a shared error:

final User? user = await dorm.users.repository.peek(userId);
final List<Product> products = await dorm.products.repository.peekAll();

peek returns null for an absent identity. Collection reads return an empty list when nothing matches. A pull stream can emit null when its watched record is absent or removed.

Validation failures that happen before a provider call remain ordinary Dart errors:

For creation and identity rules, use Create records and @Model. Composite-key repositories accept explicit creation; Creation.auto is rejected by the generated type before a repository call is made.

Inspect the original backend error¶

Supported external engines expose database, driver, Firebase, and HTTP failures as DormDatabaseException. The exception keeps the original provider error and stack trace at the application boundary:

try {
  await dorm.products.repository.push(product);
} on DormDatabaseException catch (error, stackTrace) {
  print('Product write failed: ${error.kind}');
  print(error.cause);
  print(stackTrace);
}

A failure can occur while dORM builds a query, while the driver executes it, or while the backend applies its own schema, permission, or constraint rules. The selected engine page identifies the connection and configuration values that must exist before the operation can succeed.

Handle stream errors through the stream API¶

Errors from a source, relationship callback, mapping step, or backend listener are delivered through the stream error channel:

final subscription = dorm.users.repository.pullAll().listen(
  (users) => print('Loaded ${users.length} users'),
  onError: (Object error, StackTrace stackTrace) {
    print('User stream failed: $error');
    print(stackTrace);
  },
);

Supported external engines use DormDatabaseException for provider failures from relationships and streams. Engines without ErrorAwareEngine and dORM validation errors remain native Dart or provider errors. See Portable database errors.

Check engine-specific callback behavior¶

patch combines a read, a callback, and a write or removal. Error propagation is implemented by each engine. For example, Firebase handles callback failure inside its transaction path, while the SQL adapters follow their driver transaction futures. Do not assume that the same callback error has identical propagation behavior across engines.

For the framework-level signatures and return values, see Framework contracts.