Error Handling

Because FMTC has complex internals that rely heavily on external factors and preconditions being met, it is important to properly anticipate, catch, and handle errors & exceptions.

Errors & exceptions in FMTC come in two primary forms:

• Errors: usually generated by FMTC & descended from FMTCBackendError These indicate incorrect usage on the user's part - for example, an incorrect assumption such as usage of a method on a store before initialisation. These may also be non-specfic types, such as ArgumentError.

• Exceptions: usually generated by the depdenencies of backends, such as databases These indicate some sort of unexpected failure, such as a database reaching its maximum size limit during a write operation. These are usually not generated/typed by FMTC, and so are often of types from other libraries, such as ObjectBox when using the default FMTCObjectBoxBackend.

The difference between errors & exceptions extends beyond FMTC, and is a general concept in Dart. See this post for more information about the difference between Exceptions and Errors.

Exceptions may be caught using standard try/catch blocks (it's not usually recommended to catch FMTCBackendErrors).

FMTC automatically adjusts and changes the thrown StackTrace to include useful additional info, and ensures that the trace is followed across the many isolates and asynchronous gaps (eg. streams) of the FMTC internals. When creating a bug report, please include the full trace, including debug info at the end, if any is available.

It can usually be assumed that the requested operation did not & will not complete when an exception is thrown from it.

During Initialisation

One particular place where exceptions can occur more frequently is during initialisation. The code sample above includes a try/catch block to catch these errors. If an exception occurs at this point, it's likely unrecoverable (for example, it might indicate that the underlying database has been corrupted), and the best course of action is often to manually delete the FMTC root directory from the filesystem.

The default directory can be found and deleted with the following snippet (which requires 'package:path' and 'package:path_provider':

import 'dart:io';

import 'package:path/path.dart' as path;
import 'package:path_provider/path_provider.dart';

final dir = Directory(
  path.join(
    (await getApplicationDocumentsDirectory()).absolute.path,
    'fmtc',
  ),
);

await dir.delete(recursive: true);

// Then reinitialise FMTC