@@ -129,34 +157,131 @@ Sentry's Flutter SDK doesn't currently support the `uploadNativeSymbols` flag fr
## Configuration Reference
-The following table lists all available configuration options for the Sentry Dart Plugin:
-
-
-
-| Option | Type | Default | Description | Environment Variable |
-|--------|------|---------|-------------|---------------------|
-| `project` | string | | **Required.** Your project's name (e.g., `sentry-flutter`) | `SENTRY_PROJECT` |
-| `org` | string | | **Required.** Your organization's slug (e.g., `sentry-sdks`) | `SENTRY_ORG` |
-| `auth_token` | string | | **Required.** The Sentry auth token | `SENTRY_AUTH_TOKEN` |
-| `upload_debug_symbols` | boolean | `true` | Enables or disables automatic upload of debug symbols | |
-| `upload_source_maps` | boolean | `false` | Enables or disables automatic upload of source maps | |
-| `upload_sources` | boolean | `false` | Enables or disables source code upload | |
-| `dart_symbol_map_path` | string | | Absolute or relative path to the Dart symbol map file used to make obfuscated Flutter issue titles readable on iOS and Android | |
-| `url` | string | | The URL of your Sentry instance | `SENTRY_URL` |
-| `url_prefix` | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - |
-| `wait_for_processing` | boolean | `false` | Whether to wait for server-side processing of uploaded files | |
-| `log_level` | string | `warn` | Configures the log level for sentry-cli (`trace`, `debug`, `info`, `warn`, `error`) | `SENTRY_LOG_LEVEL` |
-| `release` | string | `name@version` from pubspec | The release version for source maps | `SENTRY_RELEASE` |
-| `dist` | string | | Custom distribution identifier | `SENTRY_DIST` |
-| `web_build_path` | string | `build/web` | The web build folder path | |
-| `commits` | string | `auto` | Release commits integration | |
-| `ignore_missing` | boolean | `false` | Ignore missing commits previously used in the release | |
-| `bin_dir` | string | `.dart_tool/pub/bin/sentry_dart_plugin` | The folder where the plugin downloads the sentry-cli binary | |
-| `bin_path` | string | | Path to a sentry-cli binary to use instead of downloading | |
-| `sentry_cli_cdn_url` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli | `SENTRYCLI_CDNURL` |
-
-
+The following table lists all available configuration options for the Sentry Dart Plugin.
+
+The **Key** column refers to the option name used in:
+
+- `pubspec.yaml`
+- `sentry.properties`
+- `--sentry-define`
+
+When available, environment variable names are listed in the **Environment Variable** column.
+
+| Key | Environment Variable | Type | Default | Description |
+| -------------------------- | ------------------- | ------- | --------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `project` | `SENTRY_PROJECT` | string | | **(Required)** Your project's name (e.g., `sentry-flutter`) |
+| `org` | `SENTRY_ORG` | string | | **(Required)** Your organization's slug (e.g., `sentry-sdks`) |
+| `auth_token` | `SENTRY_AUTH_TOKEN` | string | | **(Required)** The Sentry auth token |
+| `upload_debug_symbols` | — | boolean | `true` | Enables or disables automatic upload of debug symbols |
+| `upload_source_maps` | — | boolean | `false` | Enables or disables automatic upload of source maps (Flutter Web) |
+| `upload_sources` | — | boolean | `false` | Enables or disables source code upload |
+| `dart_symbol_map_path` | — | string | | Path to the Dart symbol map file for readable obfuscated issue titles |
+| `release` | `SENTRY_RELEASE` | string | `name@version` from pubspec | The release version for source maps |
+| `dist` | `SENTRY_DIST` | string | Build number (after `+` in version) | Custom distribution identifier |
+| `build_path` | — | string | `build` | Base build directory |
+| `web_build_path` | — | string | `web` | The web build folder path relative to `build_path` |
+| `symbols_path` | — | string | `.` | The directory containing debug symbols. This recursively searches for debug files. |
+| `url` | `SENTRY_URL` | string | | The URL of your Sentry instance (for self-hosted) |
+| `url_prefix` | — | string | | URL prefix for JS source maps (e.g., `~/`). Required for non-root web deployments |
+| `legacy_web_symbolication` | — | boolean | `false` | Uses legacy symbolication for Flutter Web. See [Debug IDs](#debug-ids-flutter-web) |
+| `commits` | — | string | `auto` | Release commits integration |
+| `ignore_missing` | — | boolean | `false` | Ignore missing commits previously used in the release |
+| `wait_for_processing` | — | boolean | `false` | Whether to wait for server-side processing of uploaded files |
+| `log_level` | `SENTRY_LOG_LEVEL` | string | `warn` | Log level for sentry-cli: `trace`, `debug`, `info`, `warn`, `error` |
+| `bin_dir` | — | string | `.dart_tool/pub/bin/sentry_dart_plugin` | Folder where the plugin downloads the sentry-cli binary |
+| `bin_path` | — | string | | Path to a sentry-cli binary to use instead of downloading |
+| `sentry_cli_cdn_url` | `SENTRYCLI_CDNURL` | string | `https://downloads.sentry-cdn.com/sentry-cli` | Alternative place to download sentry-cli |
+| `sentry_cli_version` | — | string | | Override the sentry-cli version to download |
+
+## Features
+
+The Sentry Dart Plugin uploads debug symbols and source maps to make your Flutter errors readable. Here's what you get on each platform:
+
+### Mobile & Desktop — Non-Obfuscated Builds
+
+| Feature | iOS | Android | macOS | Windows | Linux |
+| -------------------- | --- | ------- | ----- | ------- | ----- |
+| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* |
+| Symbolicated Issue Title | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+### Mobile & Desktop — Obfuscated Builds (`--obfuscate`)
+
+| Feature | iOS | Android | macOS | Windows | Linux |
+| -------------------- | ------- | ------- | ------------- | ------------- | ------------- |
+| Symbolicated Stacktrace | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Source Context | ✓\* | ✓\* | ✓\* | ✓\* | ✓\* |
+| Symbolicated Issue Title | ✓ | ✓ | Not Supported | Not Supported | Not Supported |
+
+\*Requires `--split-debug-info` build flag supplied to the `flutter build` command
+
+### Web (Always Minified)
+
+| Feature | Support |
+| -------------------- | ------------- |
+| Symbolicated Stacktrace | ✓ |
+| Source Context | ✓ |
+| Symbolicated Issue Title | Not Supported |
## Troubleshooting
-If you encounter any issues with the Sentry Dart Plugin, refer to [Troubleshooting - Sentry Dart Plugin](/platforms/dart/guides/flutter/troubleshooting#sentry-dart-plugin) for solutions to common problems.
+
+
+The plugin fails because a previous release cannot be found in the git history.
+
+Set `ignore_missing: true` in your configuration to bypass this validation:
+
+```yaml {filename:pubspec.yaml}
+sentry:
+ ignore_missing: true
+```
+
+
+
+
+
+Source maps aren't working for Flutter Web with plugin version 3.0.0+.
+
+Upgrade your Sentry Flutter SDK to 9.1.0+.
+
+If you're using a version of the Sentry Flutter SDK earlier than 9.1.0, you can set `legacy_web_symbolication: true` to use the legacy symbolication method.
+
+
+
+
+
+Source maps aren't matching for a Flutter Web app that's not deployed at the root URL (e.g., `https://example.com/my-app/` instead of `https://example.com/`).
+
+Configure both the `url_prefix` in the plugin and update your stack frame paths in the SDK to match.
+
+**Step 1:** Add the `url_prefix` to your plugin configuration:
+
+```yaml {filename:pubspec.yaml}
+sentry:
+ upload_source_maps: true
+ url_prefix: ~/my-app/
+```
+
+**Step 2:** Update the stack frame paths using `beforeSend` so they include the same prefix. This allows Sentry to match the source maps correctly:
+
+```dart
+options.beforeSend = (event, hint) {
+ for (final exception in event.exceptions ?? []) {
+ final stackTrace = exception.stackTrace;
+ if (stackTrace != null) {
+ for (final frame in stackTrace.frames) {
+ // Replace with your actual domain and path prefix
+ const baseUrl = 'https://example.com/';
+ final modifiedAbsPath = frame.absPath?.replaceFirst(
+ baseUrl,
+ '${baseUrl}my-app/',
+ );
+ frame.absPath = modifiedAbsPath;
+ }
+ }
+ }
+ return event;
+};
+```
+
+