Flutter — Error Tracking

Introduction

Lerix captures errors and exceptions from your Flutter app so you can debug issues faster. After you complete the Flutter installation, use Lerix.throwError to send custom errors or caught exceptions to your dashboard.

Make sure you have initialized the SDK with Lerix.init() before reporting errors.

Report an error

Use Lerix.throwError to manually report an error. This is useful when you catch an exception in a try/catch block and want to send it to Lerix with extra context.

main.dart

try {
  await riskyOperation();
} catch (e, stack) {
  await Lerix.throwError(
    e,
    stack,
    bugSeverity: BugSeverity.high,
    metaData: {
      'userId': '123',
      'action': 'payment',
      'amount': 100.0,
    },
  );
}

Parameters

Parameter	Type	Required	Description
`error`	`Object`	Yes	Error object or message
`stack`	`StackTrace`	Yes	Stack trace associated with the error
`bugType`	`BugType`	No	Bug classification
`bugSeverity`	`BugSeverity`	No	Severity level
`metaData`	`Map<String, dynamic>`	No	Additional context to attach to the report

`BugType` values

Value	Description
`runtimeError`	An unhandled exception thrown at runtime
`logicBug`	Incorrect behavior that doesn’t throw
`uiBug`	A visual or layout defect
`networkError`	A failed or malformed network request
`performance`	Slowness, jank, or excessive resource use
`compatibility`	Breaks on a specific device, OS version, or platform
`validationError`	Invalid input passed validation it shouldn’t have
`security`	A security-relevant defect
`crash`	The app terminated unexpectedly
`unknown`	None of the above

`BugSeverity` values

Value	Description
`critical`	Blocks core functionality or affects all users
`high`	Serious impact, but a workaround exists
`medium`	Noticeable but limited impact
`low`	Minor or cosmetic
`unknown`	Severity not yet assessed

Automatic error capture

Once Lerix.init() has run, uncaught Flutter framework errors (via FlutterError.onError) and uncaught Dart errors (via PlatformDispatcher.instance.onError) are captured and sent automatically — you don’t need to wrap your whole app in a try/catch to get baseline coverage. Lerix.throwError is for cases you catch yourself and want to add classification or metadata to. Uncaught errors are reported as critical crashes on every platform, including Flutter Web.

Flutter Web release builds are minified. To see Dart file and line numbers for web errors, upload your source maps as described in Flutter source maps. Android and iOS release builds report them without any setup.

Verify the integration

Throw a test error to confirm everything is working:

main.dart

await Lerix.throwError(
  Exception('Test error'),
  StackTrace.current,
);

Then open your dashboard — the error should appear within seconds.

Filtering errors

Requires lerix_flutter 0.3.0 or later. Two optional Lerix.init options decide which errors are sent. They apply to every report: uncaught Flutter, Dart and zone errors, Lerix.throwError, and web.

Lerix.init(
  // ...
  ignoreErrors: [
    'SocketException', // case-insensitive substring
    RegExp(r'^HttpException: 40[13]'), // RegExp, matched with hasMatch
  ],
  beforeSend: (event) {
    if (event.metadata?['test'] == true) return null; // drop it
    return event.copyWith(
      message: event.message.replaceAll(RegExp(r'token=\S+'), 'token=***'),
    );
  },
  builder: () => runApp(const MyApp()),
);

ignoreErrors (List<Pattern>) runs first. A String drops any error whose message contains it, ignoring case. Empty or whitespace-only strings are skipped. A RegExp drops any error whose message it matches.
beforeSend then gets a LerixErrorEvent (message, stack, type, severity, metadata). Return it to send it, return a changed copy from copyWith, or return null to drop it. If beforeSend throws, the original report is sent and the exception is never rethrown into your app.
A dropped report is not sent and doesn’t call onError.
The message you match against is the issue title, which includes the error class.

Lerix also groups repeated errors into one issue and filters common noise on the server, for every SDK version. See How errors are grouped into issues.

Getting started

Frameworks

Modules

Developers

Flutter — Error Tracking

Introduction

Report an error

Parameters

`BugType` values

`BugSeverity` values

Automatic error capture

Verify the integration

Filtering errors

​Introduction

​Report an error

​Parameters

​BugType values

​BugSeverity values

​Automatic error capture

​Verify the integration

​Filtering errors

Introduction

Report an error

Parameters

`BugType` values

`BugSeverity` values

Automatic error capture

Verify the integration

Filtering errors