Skip to content

docs(flutter): document Android flavor workaround for split-debug-info #17268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
denrase wants to merge 5 commits into
base: master
Choose a base branch
from
+35 −1
Open

docs(flutter): document Android flavor workaround for split-debug-info #17268

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3ca2e79
docs(flutter): document Android flavor workaround for split-debug-info
denrase Apr 7, 2026
fa8dbe9
Merge branch 'master' into denrase/dart-plugin-android-flavor-workaround
denrase Apr 7, 2026
4ab3ea2
Merge branch 'master' into denrase/dart-plugin-android-flavor-workaround
denrase Apr 7, 2026
8ac1961
add flutter version
denrase Apr 7, 2026
3f7e7cf
Update docs/platforms/dart/guides/flutter/troubleshooting.mdx
denrase Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion docs/platforms/dart/guides/flutter/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,40 @@ The `--split-debug-info` option requires setting an output directory. The direct

Flutter's `build web` command requires setting the `--source-maps` parameter to generate source maps. See [Flutter GitHub Issue](https://github.com/flutter/flutter/issues/72150#issuecomment-755541599) for more information.

### Symbolication issues with `--split-debug-info` and Android flavors

If your app uses Android product flavors together with `--split-debug-info`, Flutter/Gradle may compile another release flavor and overwrite the selected flavor's `.symbols` files. This was confirmed for Flutter version 3.32.0 and later. As a workaround, ignore non-selected release variants in `android/app/build.gradle.kts` and pass the active flavor through the build command:
Copy link
Copy Markdown
Contributor

@buenaflor buenaflor Apr 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If your app uses Android product flavors together with `--split-debug-info`, Flutter/Gradle may compile another release flavor and overwrite the selected flavor's `.symbols` files. This was confirmed for Flutter version 3.32.0 and later. As a workaround, ignore non-selected release variants in `android/app/build.gradle.kts` and pass the active flavor through the build command:
<Alert>
Affected versions: Flutter 3.32.0 and later
</Alert>
When using Flutter Android product flavors with the `--split-debug-`info flag, Gradle may compile other release flavors in addition to the one you selected. This can cause the `.symbols` files for your selected flavor to be overwritten by a different flavor's build output, resulting in mismatched or unusable debug symbols.
#### Workaround
1. In `android/app/build.gradle.kts`, disable compilation for any release variants you aren't actively building. This prevents Gradle from overwriting your selected flavor's symbols.
2. Pass the active flavor explicitly in your build command so Gradle only processes the variant you need.


```kotlin
android {
variantFilter {
// Only keep the selected release flavor to avoid split-debug-info
// being overwritten by other release variants.
if (buildType?.name != "release") return@variantFilter

val activeFlavor = (project.findProperty("active-flavor") as String?)
?.lowercase()
?: return@variantFilter

val variantFlavors = flavors.map { flavor -> flavor.name.lowercase() }
if (activeFlavor !in variantFlavors) {
ignore = true
}
}
}
```

Build with matching values for `--flavor` and `active-flavor`:

```bash
flutter build appbundle \
--flavor=googlePlay \
--target=lib/main_googlePlay.dart \
--obfuscate \
--split-debug-info=debug_info/googlePlay \
--android-project-arg=active-flavor=googlePlay
Copy link
Copy Markdown

@sentry sentry bot Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The suggested workaround may fail silently. If the --android-project-arg flag doesn't set the Gradle property as expected, the variantFilter logic is bypassed, and no build variants are filtered.
Severity: MEDIUM

Suggested Fix

Verify that --android-project-arg correctly passes the property to the variantFilter block. Add a log statement or error handling to the Kotlin script to warn the user if the active-flavor property is not found. Update the documentation with steps for the user to confirm the workaround is active.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: docs/platforms/dart/guides/flutter/troubleshooting.mdx#L153

Potential issue: The documentation suggests a workaround using the
`--android-project-arg=active-flavor=googlePlay` flag to filter Android build variants.
The corresponding Kotlin code retrieves this value using
`project.findProperty("active-flavor")`. If the flag fails to set the Gradle property,
`findProperty` returns `null`, causing the logic to exit silently (`?:
return@variantFilter`). This bypasses the intended variant filtering, leading to a
silent failure where users believe the workaround is active, but it provides no
protection against the original issue of overwritten `.symbols` files.

Did we get this right? 👍 / 👎 to inform future reviews.

```

## Issues with native crashes on Linux and/or Windows

By default the Sentry Flutter SDK will enable native crash reporting on Linux and Windows with `crashpad`.
Expand All @@ -131,7 +165,7 @@ On Linux, compiling your Flutter Desktop app with the crashpad backend can fail

- Update your clang to at least version 13, then try again.
- If you still encounter errors, please file an issue on our [Sentry Dart GitHub repository](https://github.com/getsentry/sentry-dart/issues/).

### Java or JNI Errors when compiling on Flutter Desktop

Since Sentry Flutter SDK version `9.0.0`, we improved how the SDK works on Android by switching from method channels to JNI (Java Native Interface) for certain operations.
Expand Down
Loading