Gradle OOM on Android builds: just give the JVM more heap

Android build was failing partway through with a Gradle OutOfMemoryError. First few times I assumed it was a flaky CI worker. Then it failed locally too.

What was happening

Execution failed for task ':app:mergeDebugResources'.
> A failure occurred while executing com.android.build.gradle.internal.workeractions
   > java.lang.OutOfMemoryError: Java heap space

It happened on the first build after a fresh clone, and on builds where I'd touched native dependencies. Subsequent builds with the cache warm usually worked. So it correlated with the heavyweight resource merge and native dep compilation stages.

What I found

The Gradle daemon JVM defaults to a 512 MB max heap. That's fine for tiny projects. For anything with React Native modules, a meaningful native dependency tree, or a few thousand drawables, 512 MB is comfortably less than the build process actually needs. The OOM is just Gradle hitting the ceiling.

The fix

One line in gradle.properties:

org.gradle.jvmargs=-Xmx8g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

8 GB is overkill for most projects, but I'd rather burn unused memory than have CI fail on the merge step. After that change the build completed cleanly, and subsequent runs are fast because the native dependency cache stays warm across builds.

If you want to be more surgical, the merge resources task in particular benefits from -Xmx4g minimum. The native compilation steps with the Android NDK can spike higher than that, so I went straight to 8.

What I'd do differently

The 512 MB default is a historical artifact and probably wrong for any modern project. I now add the heap line to gradle.properties as part of project setup, so the first build doesn't fail. Same logic for org.gradle.parallel=true — both are things that should be on by default on any machine where they're not actively a bad idea, and the friction of remembering to add them after the first failure is dumb.

# my default android gradle.properties
org.gradle.jvmargs=-Xmx8g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true
android.useAndroidX=true