How to Resolve the mergeReleaseResources IllegalStateException in Flutter

Encountering the Flutter mergeReleaseResources error with IllegalStateException and Invalid issues during an Android release build? This common Gradle build failure often occurs due to incorrect color formats, resource conflicts, or plugin issues.

Execution failed for task ':app:mergeReleaseResources'.
A failure occurred while executing com.android.build.gradle.internal.res.ResourceCompilerRunnable

Resource compilation failed (Failed to compile values resource file 
/path/to/your/project/build/app/intermediates/incremental/release/mergeReleaseResources/
merged.dir/values/values.xml. Cause: java.lang.IllegalStateException: 
Can not extract resource from com.android.aaptcompiler.ParsedResource@...)

In most cases, this indicates there is a problematic resource somewhere—often a color resource—that Android’s resource compiler can’t parse.

Below is a detailed step-by-step guide to diagnosing and fixing this flutter mergeReleaseResources error.

1. Understanding the Error

Flutter compiles your Android resources by merging all resource files: those from your own code plus any libraries or plugins. If any of these define an invalid resource—such as a color declared in an incorrect format—the merge step (mergeReleaseResources) fails with an IllegalStateException or a similar “Invalid <color>” error.

Why does it happen?

• A malformed hex value for a color (e.g., #FFF instead of #FFFFFF)
• An attribute-based color or string-based color that is incorrectly declared as <color>
• A resource name collision causing Gradle to merge incompatible definitions

2. Examine the Merged values.xml

The error message usually includes a line number—something like values.xml:37:4: Invalid <color> for given resource value. This file is located under the build output directory, typically:

{your_flutter_project}/build/app/intermediates/incremental/release/mergeReleaseResources/merged.dir/values/values.xml

1. Open the values.xml file at the indicated line.
2. Look at the exact <color> tag that causes the issue.
3. Check if the color format is valid (e.g., #RRGGBB, #AARRGGBB, etc.).

Here’s an example of an invalid entry:

<color name="myColor">#FFF</color>  <!-- This might be invalid if the compiler expects #FFF as #FFFF -->

Correct it to a valid format like #FFFFFF (6 digits for RGB) or #FFFFFFFF (8 digits for ARGB).

3. Verify Supported Color Formats

Android allows these common hex formats for colors:

• #RGB (3 hex digits)
• #ARGB (4 hex digits)
• #RRGGBB (6 hex digits)
• #AARRGGBB (8 hex digits)

Anything else (like missing digits or partial alpha values) can break the resource compilation step.
Additionally, if you’re referencing an Android theme attribute incorrectly or using a string literal like "white" inside <color>, that can also cause problems.

4. Check for Resource Name Collisions

If you (or a library) inadvertently reuse the same resource name for different resource types, the merge step can produce invalid output.

For example, if your android/app/src/main/res/values/colors.xml includes:

<color name="primaryColor">?attr/colorAccent</color>

but a library declares:

<color name="primaryColor">#FFFFFF</color>

Gradle might generate a single <color> resource that merges these references incorrectly. This sort of collision or merge mismatch can show up in the final values.xml with an invalid format.

Solution: Try renaming your color resource or removing it temporarily to see if the conflict goes away.

5. Isolate Suspicious Plugins or Libraries

Because plugins and libraries bring in their own resources, they can be the source of malformed color definitions. For example, if your logs mention a plugin like ZEGO or any other third-party library in close proximity to the error, you can:

1. Temporarily remove or comment out that plugin in pubspec.yaml.
2. Run a clean build (see next section).
3. Attempt the release build again.

If the build succeeds without that plugin, you’ve found the culprit. Then check for a newer or older version of the plugin that fixes the invalid color resource.

6. Clean and Rebuild Thoroughly

Sometimes leftover build artifacts or Gradle caches can keep an old or corrupted values.xml around. Doing an extremely thorough cleanup can help:

1. flutter clean
2. Delete the build and .gradle folders inside android/ (e.g., android/build, android/.gradle) if they still exist.
3. flutter pub get
4. (Optionally) flutter pub upgrade --major-versions to update all dependencies.
5. Re-run flutter build apk --release --verbose or ./gradlew assembleRelease --stacktrace --info for extra logs.

7. Enable Verbose or Stacktrace Logging

To get more detail on which resource triggers the crash, run:

flutter build apk --release --verbose

or from the android folder:

./gradlew assembleRelease --stacktrace --info

The console output may include the specific resource name or library module being compiled when it fails, making it easier to locate the culprit in your code or plugin dependencies.

Conclusion

An IllegalStateException during the mergeReleaseResources step in Flutter almost always points to an invalid resource. In most cases, it’s due to a malformed color entry, either in your own colors.xml or injected by a plugin. By pinpointing the offending line in the merged values.xml and verifying the color format or resource references, you can fix the issue quickly.

Key takeaways:

1. Inspect the final values.xml for an invalid color declaration.
2. Ensure all color codes match Android’s expected hex format.
3. Watch out for naming collisions among library and local resources.
4. Remove or downgrade suspicious plugins to see if they’re causing the error.
5. Clean, re-fetch, and rebuild thoroughly to remove stale caches.

Once you’ve found and corrected the malformed color or resource entry, your mergeReleaseResources step should complete successfully, allowing you to generate a release build of your Flutter app without further issues.