ErrorBoundary class

A pragmatic error boundary for Flutter apps.

What it does well

  • Provides a local place to render a fallback UI when an operation in this subtree fails and is reported through the boundary (e.g. via guardFuture, guardCallback, or guardStream).
  • Integrates with your reporting pipeline via BugReportClient.
  • Lets you decide the UX via fallbackBuilder or use a sensible default.

What it doesn't try to do

  • It does not intercept framework build/layout/paint exceptions. Those should be wired globally via BugReportBindings (see bindings.dart).

Typical usage

class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return ErrorBoundary(
      onRetry: () => context.read<ProfileCubit>().refresh(),
      child: _ProfileContent(),
    );
  }
}

class _ProfileContent extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final boundary = ErrorBoundary.of(context);

    return ElevatedButton(
      onPressed: boundary.guardAsyncCallback(() async {
        await context.read<ProfileCubit>().load();
      }, source: 'ProfileScreen.load'),
      child: const Text('Load profile'),
    );
  }
}
Inheritance

Constructors

ErrorBoundary({required Widget child, ErrorFallbackBuilder? fallbackBuilder, void onException(BaseException exception)?, VoidCallback? onRetry, bool showDetails = false, Key? key})
Wraps a subtree with error handling and reporting helpers.
const

Properties

child → Widget
The subtree the boundary wraps.
final
fallbackBuilder → ErrorFallbackBuilder?
Optional custom fallback UI when an error is captured.
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
onException → void Function(BaseException exception)?
Called whenever a BaseException is captured by this boundary.
final
onRetry → VoidCallback?
Called when the user taps "Retry" in the default fallback UI.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
showDetails → bool
Whether to show developer details (dev message, type) in the default UI.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ErrorBoundary>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

of(BuildContext context) → ErrorBoundaryState
Obtain the nearest ErrorBoundaryState from the given context.