Skip to main content

Error Handling

FDC distinguishes between validation failures, intentional operation aborts, and unexpected runtime or adapter failures.

Validation errors​

Field and record validation failures are part of the data-editing lifecycle. Handle them through normal validation configuration and, when needed, onValidationError.

final customers = FdcDataSet(
  fields: fields,
  onValidationError: (dataSet, errors) {
    showValidationMessages(errors);
  },
);

Keep business validation close to the field or dataset record validator so the same rule applies from grids, editors, and application code.

Intentional aborts​

Use FdcDataSetAbortException to veto an operation from a supported before... lifecycle callback:

beforeDelete: (dataSet) {
  final locked = dataSet.fieldByName('locked').value == true;
  if (locked) {
    throw FdcDataSetAbortException(
      'Locked customers cannot be deleted.',
    );
  }
},

An abort is a controlled workflow decision, not an adapter failure.

Dataset errors​

Use onError for dataset-level failures that should be observed centrally:

onError: (dataSet, errors, cause) {
  logger.error(
    'Dataset operation failed',
    error: cause ?? errors,
  );
},

Do not swallow errors only to keep the UI quiet. Report operational failures and show user-facing messages at the application boundary where the recovery action is understood.

Background work errors​

For async dataset work, onWorkStarted, onWorkCompleted, and onWorkError can drive progress indicators and operation-level reporting.

FdcDataSet(
  fields: fields,
  adapter: adapter,
  onWorkStarted: (dataSet, operation) {
    busyState.value = true;
  },
  onWorkCompleted: (dataSet, operation) {
    busyState.value = false;
  },
  onWorkError: (dataSet, work, error, stackTrace) {
    busyState.value = false;
    reportDataError(error, stackTrace: stackTrace);
  },
)

Adapter failures​

Custom adapters should throw meaningful exceptions when load, aggregate, or apply operations fail. JSON/REST transport implementations should preserve enough server error detail for application-level diagnostics without leaking sensitive payloads to end users.