# Add Crash Reporting to a Flutter App

Yes. An agent wires Sentry into your Flutter app's startup, router and caught exceptions, keeps the DSN out of the repo, and proves analyze and the web build pass.

[Run this on Rush](https://cloud.getrush.ai/run/add-crash-reporting/flutter/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app starts before it adds a dependency. In an app like gskinnerTeam/flutter-wonderous-app, `pubspec.yaml` names the package `wonders` at version `2.2.7+236`, pins the Dart SDK at `^3.11.5` and Flutter at `^3.41.9`, and lists `go_router`, `get_it`, `provider`, `package_info_plus`, `http` and `shared_preferences` with no crash reporter among them. `lib/main.dart` has an `async main` that calls `WidgetsFlutterBinding.ensureInitialized()`, keeps the native splash up with `FlutterNativeSplash.preserve`, registers singletons, calls `runApp(WondersApp())` and then awaits `appLogic.bootstrap()`. There is no `FlutterError.onError`, no `PlatformDispatcher.instance.onError` and no `runZonedGuarded` anywhere under `lib/`, so an uncaught exception today goes to the console and nowhere else.

It then looks for the places errors are already caught and dropped. `lib/logic/common/http_client.dart` catches `Exception` around the network call and `FormatException` when decoding a response, and `lib/logic/common/save_load_mixin.dart` catches `Exception` twice around reading and writing settings. `lib/logic/app_logic.dart` prints a message on web asking people to report problems on the GitHub issues page, which is the closest thing the app has to error reporting. `lib/router.dart` builds a `GoRouter` with a `redirect` and no `observers`, and `lib/common_libs.dart` is the barrel file every screen imports.

The agent adds `sentry_flutter` to `dependencies` with `flutter pub add`, so the lockfile moves with it, and rewrites `main` to call `SentryFlutter.init` with `appRunner` running the existing `runApp`. The DSN comes from `const String.fromEnvironment('SENTRY_DSN')`, and when it is empty the options set `enabled` to false, so a developer running `flutter run` with no define sends nothing and the file holds no secret. It sets `environment` from `kReleaseMode`, leaves release detection to the SDK, which reads the version `package_info_plus` already exposes, and adds `SentryNavigatorObserver()` to the router's `observers` so each event carries the route the person was on. In the two `catch` blocks under `lib/logic/common` it adds `Sentry.captureException(e, stackTrace: st)` with a hint naming the URL or the settings key, leaving the existing fallback behaviour as it is. In `.github/workflows/build_web.yml`, which runs `flutter build web --wasm` on Flutter `3.41.9` through `subosito/flutter-action`, it passes `--dart-define=SENTRY_DSN=${{ secrets.SENTRY_DSN }}` so the deployed web build reports and the source stays clean.

Before it pushes, the agent installs Flutter `3.41.9` in its sandbox, runs `flutter pub get`, `flutter analyze` under the repository's `flutter_lints` 6 rules with the 120 column formatter width from `analysis_options.yaml`, `dart run dependency_validator`, which the project already lists, and `flutter build web --wasm`, the same command the workflow runs. The repository has no `test/` directory, so it adds one small test that pumps `WondersApp` with the DSN empty and checks startup does not throw with Sentry disabled. It opens the pull request with those outputs quoted and a short note on which define to set for Android, iOS and web builds.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add crash reporting with Sentry to this Flutter app and open a pull request. Read pubspec.yaml, lib/main.dart, lib/logic/app_logic.dart, lib/router.dart, lib/common_libs.dart, lib/logic/common/http_client.dart, lib/logic/common/save_load_mixin.dart, analysis_options.yaml and every file under .github/workflows first. Add sentry_flutter with flutter pub add. Initialise it in main with SentryFlutter.init and appRunner around the existing runApp, read the DSN from String.fromEnvironment('SENTRY_DSN') and disable Sentry when it is empty, set the environment from kReleaseMode, add SentryNavigatorObserver to the GoRouter observers, and capture the exceptions that the existing catch blocks under lib/logic/common swallow, with a hint each. Pass the DSN into the web build workflow as a dart-define from a repository secret; never write a DSN into a file. Run flutter pub get, flutter analyze, dart run dependency_validator and flutter build web --wasm on the Flutter version the workflow pins, add one widget test that starts the app with Sentry disabled, and quote the outputs in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that changes `pubspec.yaml` and `pubspec.lock` to add `sentry_flutter`, `lib/main.dart` to initialise Sentry around `runApp`, `lib/router.dart` to add the navigator observer, `lib/logic/common/http_client.dart` and `lib/logic/common/save_load_mixin.dart` to report what they catch, `.github/workflows/build_web.yml` to pass the define, and a new `test/app_start_test.dart`. The description lists the one secret to add, `SENTRY_DSN`, and the exact `--dart-define` flag to pass to `flutter build apk`, `flutter build ipa` and `flutter run` when a developer wants a local build to report.

The evidence is the sandbox output quoted in the description and kept in full in the run's record: `flutter analyze` with its finding count, `dart run dependency_validator` showing the new package declared and used, `flutter build web --wasm` finishing, and the widget test result. The agent does not claim an event reached Sentry; without a DSN in the sandbox there is nothing to send, and the pull request says so.

Before merging, a reviewer checks that `enabled` really is false when the define is empty, that the environment names match the Sentry project's, that the hints added in the `catch` blocks do not include a response body that could carry personal data, and that the `tracesSampleRate` the agent set is as low as the team wants. Then they add the secret, merge, build once with the define and trigger a test exception to watch the first event arrive.

## Run it on every new Flutter repository

A team that starts apps from a Flutter template sends this request once per new repository from its own server: `POST /o/{org}/sessions` with this prompt and the repository URL in `resources`, one call each. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so a script can find the ones whose `pubspec.yaml` has no crash reporter and start a run for each. Each run clones its own copy, reads that app's own `main.dart` and router, and opens its own pull request.

Set a webhook URL on the API key and Rush POSTs `run.completed` or `run.failed` when a run's turn finishes, with `session_url` for your server to read the pull request link from. Send a fresh UUID as `request_id` with each request, so a retry after a network error returns the run already started instead of opening a second pull request on the same app.

## Why run it on Rush?

Adding a crash reporter to a Flutter app is a small diff with an expensive check: the right SDK version has to be installed, `pub get` has to resolve against a lockfile that pins the Flutter SDK, and the web build takes long enough that most people skip it and find out in CI. On Rush the agent installs the pinned SDK in its own sandbox, runs analyze, the dependency check and the same `flutter build web --wasm` the workflow runs, and fixes a type or lint problem before anyone sees the branch. Your laptop keeps its own Flutter channel and your working tree stays where it was.

The pull request carries proof rather than a promise. Every command and its output stay in the run's record, the diff shows the DSN arriving as a define and not as a string in `main.dart`, and the reviewer decides what merges. Because each run is independent, the same request can go to every Flutter app the team owns at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Where does the DSN live?

Nowhere in the repository. `main.dart` reads it with `String.fromEnvironment('SENTRY_DSN')`, so a build gets it from `--dart-define`, and the web workflow passes it from a repository secret. When the define is missing, the options set `enabled` to false and the app behaves exactly as before.

### Will it catch errors the app already handles?

Only where you ask. Uncaught Flutter and Dart errors are reported by `SentryFlutter.init` itself. For the `catch` blocks under `lib/logic/common` the agent adds an explicit `captureException` with a hint and keeps the existing fallback, so a failed settings read still falls back to defaults and a failed request still returns null to the caller.

### Does it work on the web build?

Yes. `sentry_flutter` supports Flutter web, and the agent runs the repository's own `flutter build web --wasm` in the sandbox to show the build still completes. The workflow change passes the DSN so the deployed site reports, while a local `flutter run -d chrome` without the define stays silent.

### Can it use Firebase Crashlytics instead?

Yes. Name it in the prompt and the agent adds `firebase_core` and `firebase_crashlytics`, wires `FlutterError.onError` and `PlatformDispatcher.instance.onError` to `recordFlutterFatalError` and `recordError`, and tells you which platform config files to add. Crashlytics has no web support, so the web build would be left reporting nothing.

### Why does it add a test when the app has none?

So the pull request includes a check that runs on a Linux runner with no device: starting `WondersApp` with Sentry disabled and asserting the first frame renders. It is deliberately small and stands as the place for the next test to go; the agent does not claim coverage of the app.

## More Flutter jobs

- [Add a Dark Theme Setting to a Flutter App from a Linear Issue](https://getrush.ai/run/add-dark-theme/flutter/)
- [Add Deep Links to a Flutter App](https://getrush.ai/run/add-deep-links/flutter/)
- [Set Up Dependabot for a Flutter App's Pub, Gradle and Actions Dependencies](https://getrush.ai/run/add-dependabot/flutter/)

## The same job on other stacks

- [Add Crash Reporting to a React Native App](https://getrush.ai/run/add-crash-reporting/react-native/)
- [Add Crash Reporting to a Tauri App](https://getrush.ai/run/add-crash-reporting/tauri/)
- [Add Sentry Crash Reporting to a Vite React App](https://getrush.ai/run/add-crash-reporting/vite-react/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
