Coder Legion - Recent posts tagged gradle

Fix Gradle Dependency Verification Failures

Sat, 17 Oct 2026 14:45:06 +0000

A Gradle dependency verification failure occurs immediately after upgrading a plugin, adding a module, bumping a library, or enabling a benchmark configuration.

Quick solution:

Run ./gradlew --write-verification-metadata sha256 to update your allowlist incrementally while preserving the security gate.

./gradlew --write-verification-metadata sha256

Gradle's dependency verification guide covers checksums, signatures, metadata generation, and verification failures. The fastest-looking fix is also the most dangerous one: delete verification-metadata.xml or disable verification until CI turns green. Do not do that by reflex.

Gradle's dependency verification exists to make unexpected artifact changes visible. A failure can mean a normal new dependency is missing from the allowlist, but a checksum mismatch can also mean the bytes are not the bytes you previously trusted. The right workflow starts by classifying the failure.

First identify which failure you actually have

Two errors that look similar have very different risk profiles.

Missing verification metadata

A typical message says the artifact has no checksum in the verification metadata. That often happens after adding a new dependency, updating a version, introducing a new test or benchmark module, resolving a previously unused configuration, or changing a plugin that pulls new transitive artifacts. This is usually an expected maintenance task, but the new hashes still need review.

Incorrect checksum

A more serious failure says Gradle expected one checksum but calculated another. That means the artifact identity changed. Possible explanations include a corrupted local cache, different repositories serving non-identical builds, a republished artifact, repository shadowing, or an actual compromised dependency. Gradle's current documentation explicitly treats incorrect checksums as a condition that requires manual investigation. Do not regenerate until green when the failure is a mismatch.

Read the verification report before changing metadata

Gradle produces a verification report that identifies the artifact and configuration involved. In CI, you can also enable more verbose console output when retrieving the HTML report is inconvenient.

The useful debugging questions are which artifact failed, whether the checksum is missing or different, which configuration resolved it, whether that configuration was introduced by the change you expected, which repository supplied the artifact, whether the version is fixed or changing, and whether you can verify the expected bytes from an authoritative source. This prevents the common mistake of assuming the dependency declared in build.gradle is the one that failed. The failing item may be a plugin artifact, POM, metadata file, test runner, Jacoco agent, or transitive dependency.

Understand why one change can produce dozens of failures

Dependency verification is global to the build. The same verification metadata applies across the root project, subprojects, buildSrc, plugins, and included builds. Adding one module can cause Gradle to resolve configurations that were never part of the previous baseline.

For Android and Kotlin projects, these less-obvious configurations often include benchmark runtime classpaths, test fixtures, lint tooling, code coverage agents, Kotlin compiler plugins, Gradle plugins and their metadata, and included builds. That is why adding a single module can become dozens of failed artifacts. It is not necessarily independent problems. It may be one new dependency graph that has never been recorded.

Generate new metadata incrementally

Gradle supports generating verification metadata directly. For projects using signature verification as well, use the combined flag:

./gradlew --write-verification-metadata sha256,pgp

Generation is incremental. Existing information can be preserved while Gradle adds newly resolved artifacts. That is better than deleting the file and rebuilding trust from scratch. A safer maintenance sequence is to keep the current verification file, reproduce the failing resolution, generate the missing metadata, inspect the Git diff, verify the new entries, rerun the build, and commit code and reviewed verification changes together.

Use dry-run output to inspect broad changes

If an upgrade would add many entries, previewing the generated metadata can make review easier. Gradle documents a dry-run mode that writes a separate verification metadata file instead of replacing the main one:

./gradlew --write-verification-metadata sha256 help --dry-run

Be aware of the limitation: a dry run does not execute tasks, so dependencies resolved only during task execution can be missing from the preview. That matters for Android pipelines where instrumentation, benchmark, code generation, or packaging tasks pull additional artifacts.

Review generated entries carefully

Generated metadata is not automatically verified truth. Gradle marks automatically produced trust information so maintainers can distinguish generated values from values they have reviewed.

The review process should ask whether the group, module, and version are expected, whether it came from the repository you intended, whether the dependency change was present in the lockfile or build diff, whether the artifact is signed, whether the checksum can be compared with an authoritative distribution, and whether the update unexpectedly introduced another repository. For critical build tooling, take the time to verify the source independently before changing an entry's provenance.

Never turn a mismatch into a missing-checksum workflow

Suppose CI reports an expected sha256 that differs from the actual sha256. Running write-verification-metadata immediately can normalize the new bytes into your trusted file and erase the warning you needed to investigate.

Instead, clear only the suspect cached artifact and redownload it, confirm the repository endpoint, compare the artifact with an upstream checksum or signature when available, inspect whether the publisher legitimately republished the same version, and accept an additional checksum only when you understand why the variation exists.

Keep verification changes reviewable in Git

verification-metadata.xml belongs in version control. A good pull request makes the relationship obvious between the dependency version change, the verification metadata change for that dependency graph, and the CI verification run. Avoid bundling unrelated checksum churn with an unrelated feature.

CI needs the same resolution path

A local build can pass while CI still fails because the two environments resolve different tasks. Examples include CI running macrobenchmark tasks, downloading sources, enabling release variants, or resolving artifacts missing from a warm local cache. The fix is not to add random hashes until CI becomes quiet. Reproduce the exact CI task set and generate metadata through that resolution path.

Verification and execution checklist

Preserve the existing metadata file instead of deleting it entirely.
Classify missing metadata versus mismatched checksum before running generators.
Inspect the exact artifact and configuration from the failure report.
Reproduce the failing resolution path locally using the exact build configuration.
Generate missing data incrementally using the Gradle flags and review every new entry in the Git diff.

Conclusion

Dependency verification is supposed to interrupt you. The interruption is useful because dependencies are executable inputs to your build. When one of those inputs changes unexpectedly, a secure pipeline should make you explain why. The goal is not to make verification stop complaining, but to make the new dependency graph understood, reviewed, and reproducible.

Minimum Weight: Code Coverage Gates in Kotlin Multiplatform with Kover

Wed, 23 Sep 2026 09:00:00 +0000

After a GT race, every car rolls onto the weighbridge before parc fermé. It has to clear a minimum weight, set before the season and revised only upward as the series collects more data on what's fair. A car that comes in light gets disqualified, no matter how well it drove. Teams don't get to argue the number down when it's inconvenient. They add ballast, or they find grip somewhere else.

I think about that weighbridge every time I look at a coverage report.

A percentage on its own tells you almost nothing. Ninety percent coverage on a module full of generated code and empty getters is worse than sixty percent on a module where every line was actually exercised by a test that would fail if you broke something. I found this out the annoying way, wiring Kover into a project with close to twenty modules: the number moved, but it wasn't telling me the truth.

The number was lying before it was useful

The first pass was simple. Apply the Kover plugin, point it at every module, generate a report. The merged number came out somewhere in the low sixties. Respectable enough on paper, wrong in a way that mattered.

Domain modules with almost no real logic were sitting near the top of the report, and it wasn't because they were well tested. It was because a dependency injection library had generated a pile of factory classes and graph interfaces that every counted line inflated the denominator on, without a single one of them ever being able to fail a test. Compose @Preview functions did the same thing in the other direction: pure decoration, zero tests, dragging modules with real logic down next to modules that had none.

You can't set a meaningful floor on a number built like that. So before the floor came the exclude list, and before the exclude list came trusting the report at all.

Coverage across more than one module

A single-module Android app can get away with Kover's defaults: apply the plugin, run koverHtmlReport, done. A multi-module KMP project can't, for two reasons.

First, most modules don't need coverage measured at all. Pure API modules, thin platform-wrapper modules, anything with no meaningful branches, don't need a plugin dragging a bytecode instrumentation step into every build. Second, the number you actually care about is the merged one across every module that does carry logic, not twenty separate reports you have to average in your head.

The way I did was creating a convention plugin that applies Kover to a module and defines the excludes, plus a root-level aggregation that pulls the modules worth measuring into one merged report.

// build-logic/convention/src/main/kotlin/KoverConventionPlugin.kt
class KoverConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            val libs = the<LibrariesForLibs>()
            pluginManager.apply(libs.plugins.kover.get().pluginId)

            extensions.configure<KoverProjectExtension> {
                reports {
                    filters {
                        excludes {
                            classes(
                                // DI-generated factories and contribution classes.
                                "*\$Factory*",
                                "*\$ContributionToAppScope*",
                                // Compose-compiler-generated lambda holders, no logic of their own.
                                "*ComposableSingletons*",
                                "*Previews",
                                "*PreviewsKt",
                                // Generated resource accessors.
                                "*.generated.resources.*",
                                // Pure DI wiring: every class under a `.di.` package here
                                // is graph construction, nothing to unit test.
                                "*.di.*",
                            )
                        }
                    }
                }
            }
        }
    }
}

Any module with tests worth counting applies this plugin instead of wiring Kover from scratch:

// core/network/build.gradle.kts
plugins {
    id("template.kover")
    // ...other convention plugins
}

The root project then declares which modules feed the merged report, and repeats the same excludes so the merged view and each module's own view agree with each other:

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.kover)
}

dependencies {
    // Only modules with real tests are listed here. A module with nothing
    // to measure doesn't need to show up in the merged number at all.
    kover(project(":core:common"))
    kover(project(":core:network"))
    kover(project(":core:database"))
    kover(project(":feature:auth:domain"))
    kover(project(":feature:auth:data"))
    kover(project(":feature:profile:presentation"))
}

kover {
    reports {
        filters {
            excludes {
                // Keep in sync with KoverConventionPlugin's excludes.
                classes(
                    "*\$Factory*",
                    "*\$ContributionToAppScope*",
                    "*ComposableSingletons*",
                    "*Previews",
                    "*PreviewsKt",
                    "*.generated.resources.*",
                    "*.di.*",
                )
            }
        }
    }
}

That "keep in sync" comment is doing real work. Kover reads excludes from wherever the report is generated. Exclude a class in the convention plugin but forget the same line in the root aggregation, and the merged report counts it again, quietly, and your floor starts failing for a reason that has nothing to do with a real regression.

Excluding the honest way

The instinct when a module reads 0% is to exclude your way to a better number. That's the wrong direction to pull. The right question for anything you're about to exclude is: could a test on this class ever fail for a real reason? If yes, it stays in the count, even if writing that test is annoying. If no, excluding it isn't gaming the number, it's correcting a measurement error.

Generated database entities and query classes are the clearest case. A SQLDelight-generated UserEntityQueries class has no branches a test could meaningfully assert on beyond "does the generated SQL run," which your actual repository tests already cover indirectly.

excludes {
    classes(
        "com.example.app.core.database.UserEntity",
        "com.example.app.core.database.UserEntityQueries",
        "com.example.app.core.database.UserEntityQueries\$*",
    )
}

The exclude list will grow every time you add a code generator. A new annotation processor, a new resource pipeline, a new DI library migration, each one leaves generated classes in its wake that need the same treatment. Treat additions to this list the same way you'd treat additions to .gitignore: expected maintenance, not a sign something's wrong.

The floor that only goes up

Once the report was honest, setting a floor was the easy part.

kover {
    reports {
        verify {
            rule {
                // Baseline was ~64% after excluding generated code.
                // Raised to 68% once core/network got real coverage.
                // Raised to 75% after the auth data layer got tests
                // for its *RepositoryImpl classes.
                // Never lower this to make a failing build pass.
                minBound(75)
            }
        }
    }
}

koverVerify fails the build if merged line coverage drops below that number. The number itself is a ratchet, not a target. Every time real tests push the baseline up, the floor moves up behind it, a couple of points below the current baseline so unrelated refactors don't fail the build on noise. It never moves down. If a change makes coverage drop, the fix is to write the missing tests, not to edit the floor.

That's the whole point of the weighbridge analogy holding up under pressure. A minimum weight limit that teams could talk their way under whenever it was inconvenient wouldn't be a rule, it would be a suggestion. Same with a coverage floor you lower the first time it's in your way.

Wiring it into CI

Locally, koverVerify runs alongside koverHtmlReport and koverXmlReport as part of the same pre-merge check that runs Detekt (covered in The White Lines). Coverage belongs in the same slot: a gate that runs before a PR is allowed to merge, not a report someone checks manually once a month.

If your KMP project already has a GitHub Actions workflow running unit tests on every pull request, adding a coverage gate is one more step, not a new pipeline:

# .github/workflows/tests.yml
name: Unit Tests
on:
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: 'gradle'

      - name: Run unit tests
        run: ./gradlew testDebugUnitTest --max-workers=2

      - name: Enforce coverage floor
        run: ./gradlew koverXmlReport koverVerify

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: kover-report
          path: build/reports/kover/

koverVerify fails the job the same way a failing test does, so there's no extra branching logic to write. The XML report is worth generating even if nothing downstream reads it yet: it's the format most coverage-badge and PR-annotation tools expect, and generating it costs nothing extra once koverXmlReport is already in the command.

One gotcha if you're running this on Android modules with Robolectric tests: those tests are memory-hungry, and Kover's instrumentation adds overhead on top. If the job runs out of memory before it gets anywhere near reporting a real coverage number, raise the runner's heap before you start suspecting the plugin:

env:
  GRADLE_OPTS: -Dorg.gradle.jvmargs="-Xmx4g -XX:MaxMetaspaceSize=1g"

The line I hold

A coverage percentage nobody enforces is decoration. It sits at the top of a README, it looks fine in a badge, and it means nothing because there's no consequence when it drops. The moment koverVerify runs on every pull request and fails the build, the number stops being decoration and starts being a rule the team actually has to answer to.

I'd rather have a floor at seventy-five that only goes up than a badge that says ninety and hasn't been checked since the module was scaffolded.

Everyone crosses the weighbridge. Nobody gets to argue the number down. 🏁

Same Car, Every Time: Deterministic Feature Module Generation in KMP

Tue, 15 Sep 2026 14:00:00 +0000

Walk down the pit lane at a Porsche Cup weekend and every garage holds the same car. Same chassis from the same jig, same engine sealed by the same people, same tolerances checked against the same sheet. Nobody on that grid gets to be creative about the monocoque. It isn't a lack of ambition, it's the entire point: when thirty cars are identical, a tenth of a second means something. You learn from the difference because the baseline never moves.

A Formula 1 grid gives you brilliant engineering and twenty-two cars where no two problems have the same cause. Both are real forms of racing. They answer different questions.

Feature modules are a spec series. I want every one of mine built to the same jig, so that when a module behaves oddly I know it's the code I wrote and not the scaffold it arrived in. It took me a while, and one AI-generated codebase, to work out that I'd been running Formula 1.

A while back I wrote about custom Gemini commands in Android Studio, and the one I used most was the one that created KMP feature modules. The argument was simple: write down what your project looks like once, stop explaining it from scratch every time. I still believe that. The command file worked.

Then I went back and read three features I'd generated over about two months.

One had implementation(project(":feature:x:domain")) inside commonMain.dependencies. One had it at the top level of the kotlin block. One had it in both places, which somehow still compiled. The ViewModel in the oldest one extended a base class signature I'd changed since. The package for a hyphenated feature name had come out as user-profile in one file and user_profile in the rest, so that module simply didn't build until I fixed it by hand.

None of these were dramatic failures. Every single one was a five minute fix. But five minutes times four files times every feature is exactly the interruption I built the command to avoid, and now I was paying it at review time instead of at creation time, which is worse, because at review time I've already stopped thinking about this feature.

So I stopped asking and wrote a bash script.

The thing I actually wanted was not intelligence

Here's the part that took me embarrassingly long to accept: for this specific job, the AI's greatest strength is the problem.

An AI generator reads your instructions, reads your codebase, and produces something reasonable. "Reasonable" is a range. It has to be, because the model is inferring intent every time. Ask it twice and you get two points inside that range, both defensible, neither identical. That's exactly what you want when the task is genuinely novel and you can't specify it up front.

Scaffolding is not that task. Scaffolding is the opposite of that task. I know precisely what the output should be, down to the import order, because I wrote the module it's copying. There is nothing to infer. Every degree of freedom the model has is a degree of freedom I didn't ask for.

What I wanted was a fixed baseline. Not better output, identical output, so that any difference between two modules is information rather than noise.

Which raises the fair question of why bash, when a Gradle plugin or an IntelliJ file template would also be deterministic. Both were on the table. The template lost because it stops at files: it can't append to settings.gradle.kts or splice a route into an existing sealed interface, which is most of what makes a new module actually usable. The Gradle plugin lost on cost. It's the better answer if you're handing this to a team of fifteen, but it's a build-logic module to maintain and a Gradle build to re-run to test a change, whereas the script is one file I can read top to bottom and edit in place. If the thing ever outgrows bash I'll port it. It hasn't.

What the script generates

scripts/new-feature.sh takes a kebab-case feature name and produces up to three Gradle modules under feature/<name>/: domain, data, presentation. It mirrors the smallest real feature in the project, so the output isn't an idea of what my modules look like, it's a copy of one that already ships.

./scripts/new-feature.sh wishlist

That gives you:

feature/wishlist/domain with a WishlistRepository interface
feature/wishlist/data with WishlistRepositoryImpl, bound through Metro
feature/wishlist/presentation with WishlistState, WishlistEvent, WishlistAction, WishlistNavigator, WishlistViewModel, WishlistScreen, plus a WishlistGraph and WishlistGraphNavigator under navigation/
three include(...) lines appended to settings.gradle.kts
a NavigationRouter.Wishlist.Main route spliced into NavigationRouter.kt

It compiles and runs immediately. The screen is a PlaceholderScreen inside a ScaffoldScreen, the repository interface is empty, and the state holds a single Unit field so the data class is valid. Nothing pretends to be finished.

A note on the code you're about to read: this is my script, shaped around my project. The paths, the package com.example.template, Metro for DI, Navigation 3, StateViewModel and BaseState from my core/ui module, the template.* convention plugins. Dropped into your codebase as-is it won't generate anything that compiles, and that's expected rather than a problem. The value of a generator like this comes from it knowing your conventions, so the interesting part is the structure, not the contents. If you're on Koin instead of Metro, or MVI instead of this MVVM split, or one module per feature instead of three, the shape of the script stays and every heredoc inside it becomes yours. Treat what follows as a worked example to adapt.

The name handling is the first thing that stops being a per-feature annoyance:

# kebab-case -> snake_case (Kotlin package segment) and PascalCase (class name prefix)
SNAKE="${KEBAB//-/_}"
PASCAL=""
IFS='-' read -ra WORDS <<< "$KEBAB"
for word in "${WORDS[@]}"; do
  first_upper="$(printf '%s' "${word:0:1}" | tr '[:lower:]' '[:upper:]')"
  PASCAL="${PASCAL}${first_upper}${word:1}"
done

user-profile becomes the folder user-profile, the package segment user_profile, and the class prefix UserProfile. Three forms of the same name, derived once, used everywhere. This is the exact transformation an AI gets right most of the time. "Most of the time" is what shipped me a module that didn't build.

Guardrails come before generation

The script writes into feature/, appends to settings.gradle.kts, and rewrites NavigationRouter.kt in place. Something that edits tracked files without asking should be paranoid about it, so nothing gets written until three checks pass. Two are obvious: the name has to match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, and feature/$KEBAB must not already exist. The third is the one I care about:

if [[ -n "$(git status --porcelain)" ]]; then
  echo "Warning: you have uncommitted changes. This script edits settings.gradle.kts and"
  echo "NavigationRouter.kt in place, and creates new files under feature/$KEBAB."
  read -r -p "Continue anyway? [y/N] " confirm
  [[ "$confirm" =~ ^[Yy]$ ]] || exit 1
fi

With a clean tree, git diff after the run is a complete, readable record of everything the script touched. With a dirty tree, the generated changes are tangled up with yours and you lose the cheapest verification you have. The script can't force a clean tree, but it can make you type y and think about it for a second.

set -euo pipefail sits at the top, so anything unexpected stops the run rather than leaving half a feature on disk.

Then I needed one module, not three

I wanted a domain and data pair with no UI. A feature that exposes a repository, consumed by an existing screen somewhere else. The script had exactly one mode: all three modules, every time.

The obvious move, if you're used to AI generation, is to go back and describe the exception. "Same as before, but skip presentation." And that works. It works right now, on the first try, which is precisely why it's a trap. Because next month I want domain alone, and the month after I want data and presentation with the domain contract living in a shared module, and each of those is a fresh description of an exception to a structure that nobody has actually written down. Every exception is a new chance for the output to drift from the last one.

Rigidity was the whole reason I wrote the script. The answer isn't to soften it, it's to make the flexibility part of the spec.

# Usage: ./scripts/new-feature.sh <feature-name> [--modules <module> [<module> ...]]
./scripts/new-feature.sh wishlist                    # domain + data + presentation
./scripts/new-feature.sh wishlist --modules domain data

Three booleans default to true, and --modules flips them all off and turns back on only what you named:

GEN_DOMAIN=false
GEN_DATA=false
GEN_PRES=false

for module in "${MODULES[@]}"; do
  case "$module" in
    domain) GEN_DOMAIN=true ;;
    data) GEN_DATA=true ;;
    presentation) GEN_PRES=true ;;
    *)
      echo "Error: unknown module '$module'. Must be one of: domain, data, presentation." >&2
      exit 1
      ;;
  esac
done

The flag accepts at most two names, deliberately. --modules domain data presentation is already the default, and offering two ways to say the same thing is how flags start rotting. If you want all three, don't pass the flag.

That cap has a hole you only find by running your own tool wrong: --modules domain domain has a length of two, passes the count check, and sets one boolean. Comparing how many booleans ended up true against how many names were typed catches it in three lines. Small thing, and the sort of edge case no amount of prompting reliably covers, because you'd have to think of it in advance to ask for it — and once you've thought of it you may as well encode it.

Notice what this is: a flag with a validated, closed set of values. The flexibility is real and it's bounded. Every combination that's allowed is a combination I decided was allowed, and the ones I didn't decide on fail loudly at argument parsing rather than quietly at compile time.

Conditionals are where the real work is

Adding the flag was twenty minutes. Making the generated code correct for each combination was the rest of the afternoon, and this is the part I think matters most.

If you generate data without domain, the data module's build.gradle.kts must not depend on a domain module that doesn't exist. Neither branch is clever, and that's the point:

if $GEN_DOMAIN; then
  cat > "feature/$KEBAB/data/build.gradle.kts" <<EOF
import com.android.build.api.dsl.LibraryExtension

plugins {
    alias(libs.plugins.template.data)
}

extensions.configure<LibraryExtension>("android") {
    namespace = "com.example.template.feature.$SNAKE.data"
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(project(":feature:$KEBAB:domain"))
        }
    }
}
EOF

and the else branch is the same file with the whole kotlin { } block gone.

Those alias(libs.plugins.template.data) lines are convention plugins from my build-logic module. Each layer gets one plugin ID, and everything else, targets, compiler options, common dependencies, lives centrally. It's the same setup I mentioned in the Gemini article. Worth noting here because it's part of why the generated Gradle files are short enough to template safely: there's very little per-module configuration left to get wrong.

The second consequence is more interesting. Without a domain module, there is no WishlistRepository, so WishlistRepositoryImpl has nothing to implement and nothing to bind. The script doesn't generate a degraded version of it. It doesn't generate it at all, and it tells you why:

echo "Note: domain not generated — feature/$KEBAB/data has no ${PASCAL}RepositoryImpl" \
  "(it would need ${PASCAL}Repository from the domain module)."

That line took a couple of iterations to get right and I'd argue it's the most valuable output the script produces. A generator that silently omits things trains you to distrust it. A generator that says "I left this out, here's the reason" is a tool you can stop checking. The absence is intentional and documented at the moment it happens, in the terminal, while you're still looking.

Same story for the route registration. NavigationRouter.Wishlist.Main only exists to be referenced by WishlistGraph, which lives in the presentation module. No presentation, no route:

if $GEN_PRES; then
  ROUTER_FILE="core/ui/src/commonMain/kotlin/com/example/template/core/ui/navigation/NavigationRouter.kt"
  # ... splice the route in
fi

Three modules, generated or not, gives eight combinations if you count naively, six that the argument parser actually allows. Every one produces code that compiles. That's the property I was buying, and it's a property you can verify by running the thing six times, which is not something you can meaningfully do with a prompt.

The one clever bit, and its escape hatch

NavigationRouter.kt is a sealed interface hierarchy, and new routes go in as nested data object declarations before the final closing brace. There's no marker comment, no anchor, just a } on its own line at the end of the file.

LAST_BRACE_LINE=$(grep -n '^}$' "$ROUTER_FILE" | tail -1 | cut -d: -f1)

Find every line that is exactly a closing brace, take the last one, extract the line number. Then rebuild the file in three pieces:

{
  head -n "$((LAST_BRACE_LINE - 1))" "$ROUTER_FILE"
  cat <<EOF

    @Serializable
    data object $PASCAL : NavigationRouter {
        @Serializable
        data object Main : NavigationRouter
    }
EOF
  tail -n "+$LAST_BRACE_LINE" "$ROUTER_FILE"
} > "$ROUTER_FILE.tmp"
mv "$ROUTER_FILE.tmp" "$ROUTER_FILE"

Everything before the brace, the new block, then the brace and anything after it. Written to a temp file and moved into place, so a failure halfway through leaves the original intact rather than truncated.

I'm aware this is line-based surgery on Kotlin source, and that it depends on a formatting convention holding. Which is why the fallback exists:

if [[ -z "$LAST_BRACE_LINE" ]]; then
  echo "Warning: couldn't find NavigationRouter.kt's closing brace — add the route manually:"
  echo "    @Serializable"
  echo "    data object $PASCAL : NavigationRouter {"
  echo "        @Serializable"
  echo "        data object Main : NavigationRouter"
  echo "    }"

If the assumption breaks, the script says so and prints exactly what you need to paste. It does not guess at an alternative insertion point. A generator that fails visibly and hands you the fix costs you thirty seconds. A generator that improvises when its assumptions break costs you a debugging session, and you won't know to start one, because it looked like it worked.

What it deliberately refuses to do

Two things the script will not touch, and both refusals are in the header comment so I can't quietly forget them.

It won't wire WishlistGraph into anything. A new feature can live in a bottom nav tab, behind a settings row, in a shared overlay, or somewhere I haven't invented yet, and that is an architecture decision with consequences. A generator making it for me is a generator making an architecture decision I didn't review.

It won't write domain logic. WishlistRepository is an empty interface with a comment telling you to define the contract. That's the actual work. The script's job was to clear a path to it.

So the run ends with a list rather than a claim of completion:

Still manual:
  - Wire WishlistGraph(onNavigation = ...) into wherever this feature actually lives
  - Fill in WishlistRepository / WishlistRepositoryImpl with real logic.
  - Run './gradlew :feature:wishlist:domain:detekt ...' (or just commit — the pre-commit hook covers it).

Building the detekt task list from the same booleans is a two-line addition, and it means the command you're told to run is always the right one for what was actually generated.

When I still reach for the AI

I want to be clear that I didn't replace one tool with a better one. I split one job into two jobs.

The script handles the part I've done forty times and will do forty more, where I know the answer and want it applied identically every time. The AI handles everything after that: the domain logic, the state modelling for a screen that doesn't resemble any other screen, the migration that touches nine files in ways I can't specify up front. That's genuinely novel work, and the ability to infer intent from a loose description is exactly what makes it useful there.

There's also a nice side effect. The AI is now working inside a codebase where every feature module has the same shape, because the shape came from a script rather than from six separate acts of interpretation. Consistent context produces better output. The rigid tool makes the flexible one work better.

A rough test I use now: if I'm about to write a prompt for the third time and it's substantially the same prompt, that's not a prompt, that's a script I haven't written yet. And if the script needs to handle a case it doesn't, the fix is a flag with a validated set of values, not a paragraph of natural language explaining the exception.

Wrapping up

The Gemini article's conclusion was that you should write down what your project looks like once. This one is the next step: for the things you do constantly, write down how as well, in something that executes rather than interprets. Not my how. Yours, with your package name and your base classes and your DI framework, which is an afternoon of work and the reason the thing is worth anything at all.

--modules is the whole argument in miniature. I needed the generator to do something it couldn't do. I could have described the exception to a model in about fifteen seconds, and I'd have described it again, slightly differently, every time since. Instead I spent an afternoon making the exception a first-class, validated, six-combinations-all-of-which-compile part of the tool. Now nobody describes anything. You pass --modules domain data and you get the same two modules I got, and the same two I'll get in November.

Boring is the feature. Six months from now the newest module and the oldest one will still be the same shape, and that is worth more to me than a generator clever enough to surprise me.

Same jig, same tolerances, same car off the truck every race weekend. The lap time is where the interesting differences belong. 🏁

How to Fix "Duplicate class ... found in modules" in React Native & Expo

Thu, 23 Jul 2026 12:36:11 +0000

If you've been developing with React Native or Expo for a while, chances are you've had a project that suddenly refuses to build for what seems like no reason.

Maybe you installed a new package. Maybe you upgraded Expo. Maybe you only changed a single dependency. You confidently run your Android build, expecting it to compile like always...

Instead, Gradle greets you with something like this:

Execution failed for task ':app:checkDebugDuplicateClasses'.

Duplicate class androidx.lifecycle.ViewModelLazy found in modules lifecycle-viewmodel-2.8.2.aar and lifecycle-viewmodel-ktx-2.6.1.aar

Duplicate class com.google.android.gms.internal.measurement.zzab found in modules play-services-measurement-base-22.0.0.aar and play-services-measurement-impl-21.6.2.aar

Duplicate class ...

At first glance, the error looks straightforward: there are duplicate classes. Easy enough, right?

Not exactly.

In reality, this is one of those Android build errors that can send you down a rabbit hole of Gradle files, dependency trees and Stack Overflow threads, only to realize the real cause was something completely different.

Let's break down what's actually happening and, more importantly, how to fix it.

Why this error happens

Every Android library included in your project contains compiled Java or Kotlin classes.

When Gradle builds your application, it combines all of those libraries into a single APK or AAB.

If two different dependencies contain the exact same class, Gradle doesn't know which version should be packaged.

Instead of guessing, it stops the build with a Duplicate class error.

The difficult part is that the dependency causing the conflict usually isn't the one shown in the error.

Very often, it's another package pulling in an older or incompatible version behind the scenes.

The most common causes

After seeing this error many times, these are usually the culprits.

1. Two libraries depend on different versions of the same package

This is by far the most common scenario.

For example:

Library A requires:

androidx.lifecycle:lifecycle-viewmodel:2.8.2

while Library B depends on:

androidx.lifecycle:lifecycle-viewmodel:2.6.1

Both versions get added to your dependency graph, eventually leading to duplicate classes.

2. An outdated React Native package

Older React Native libraries often haven't been updated for newer AndroidX or Google Play Services versions.

Even though your project is current, that one dependency may still reference libraries released years ago.

3. Expo SDK upgrades

After upgrading Expo, many native dependency versions change.

If one third-party package hasn't caught up yet, Gradle may end up resolving incompatible versions.

This is especially common immediately after major SDK releases.

4. Mixing manual native configuration with Expo-managed dependencies

Sometimes developers manually add Android dependencies that Expo already manages internally.

The result is two copies of essentially the same library.

How to fix it

There isn't one universal solution, but these steps solve the majority of cases.

Step 1 — Read the duplicated class carefully

Don't focus on the entire error.

Look specifically for the two modules involved.

For example:

lifecycle-viewmodel-2.8.2

lifecycle-viewmodel-ktx-2.6.1

Those names usually point you toward the conflicting dependency.

Step 2 — Find who is importing it

Run:

./gradlew app:dependencies

./gradlew app:dependencyInsight --dependency lifecycle-viewmodel

This shows which package is pulling each version into your project.

It's much faster than guessing.

Step 3 — Update outdated packages

If one library is significantly behind, updating it often resolves the conflict immediately.

Always check whether a newer version exists before trying complicated Gradle workarounds.

Step 4 — Clean the project

Sometimes Gradle continues using cached artifacts.

Try:

cd android

./gradlew clean

Then rebuild.

Step 5 — Regenerate native files (Expo)

If you're using Expo Prebuild:

npx expo prebuild --clean

This recreates the native Android project using your current configuration.

Step 6 — Force dependency versions (only if necessary)

Sometimes you need to force Gradle to use one specific version.

For example:

configurations.all {
    resolutionStrategy {
        force "androidx.lifecycle:lifecycle-viewmodel:2.8.2"
    }
}

Use this carefully.

If two libraries genuinely require incompatible versions, forcing one version may create runtime problems later.

How to avoid this error in the future

While duplicate class errors can't always be prevented, these habits reduce the chances considerably.

Keep Expo SDKs reasonably up to date.
Avoid abandoned React Native libraries.
Update dependencies together instead of one at a time.
Review package compatibility before major upgrades.
Avoid manually adding Android dependencies unless absolutely necessary.

When the error isn't actually the problem

One thing that makes this error frustrating is that the duplicate classes are often just a symptom.

The real issue might be:

an outdated library,
conflicting Firebase dependencies,
mixed AndroidX versions,
incompatible Google Play Services packages,
or an incomplete Expo migration.

That's why simply searching the duplicated class name doesn't always lead to the correct fix.

Understanding why those dependencies ended up together is usually more important than the class itself.

How FixMyError can help

Instead of manually digging through Gradle output, dependency trees and dozens of forum posts, you can paste the full error into FixMyError.

The tool analyzes the build log, identifies the likely source of the conflict, explains what's happening in plain English, and suggests fixes based on the specific dependencies involved.

Rather than treating every duplicate class error as identical, it tries to narrow the problem down to the actual cause behind your particular build failure.

Final thoughts

Duplicate class errors are among the most frustrating Android build issues because the message rarely points directly to the package that's responsible.

The good news is that, in most cases, the problem comes down to dependency resolution rather than something fundamentally broken in your project.

Once you identify which libraries are introducing conflicting versions, the fix usually becomes much more straightforward.

If you're currently staring at a wall of Gradle output wondering where to begin, start by identifying the conflicting modules, trace where they're coming from, and work outward from there.

It takes a bit of patience, but it's almost always easier than blindly trying random fixes from different Stack Overflow threads.

How to Fix Gradle Error: Unsupported class file major version (React Native & Expo)

Wed, 03 Jun 2026 08:49:58 +0000

If your React Native or Expo Android compilation suddenly crashes with a massive terminal stack trace pointing to an "unsupported class file major version" or claims a class file has the wrong version (e.g., wrong version 65.0, should be 61.0), your environment is caught in a silent version mismatch.

This error almost always triggers right after you upgrade your Expo SDK, bump your React Native core version, or update Android Studio.

Here is exactly why this happens, how to decode the cryptic internal version numbers, and how to get your build compiling cleanly.

Why Did This Happen Suddenly?

When React Native or Expo upgrades their framework architecture, they also upgrade the required version of the Android Gradle Plugin (AGP) inside your project.

Each version of AGP requires a strict minimum version of the Java Development Kit (JDK) to run the compilation pipeline. If your system's global terminal runtime environment or your IDE is still pointing to an older Java runtime, the build engine throws an immediate exception during the semantic analysis phase.

The Version Decoder Cheat Sheet

Java’s compiler doesn't map version numbers logically to their public marketing names. When the Gradle stack trace throws a decimal number at you, use this index to figure out what version your code is demanding:

Class file major version 66.0 = Requires Java 22
Class file major version 65.0 = Requires Java 21 (Common in newer 2025/2026 native modules)
Class file major version 61.0 = Requires Java 17 (The baseline standard for modern React Native)
Class file major version 55.0 = Requires Java 11 (Legacy)

If your terminal says wrong version 65.0, should be 61.0, your build script encountered a dependency compiled for JDK 21, but your system is executing the build toolchain using JDK 17.

Step 1: Find the Exact Path to Your Target JDK

Before making adjustments, you need to locate where the correct JDK version is actually installed on your machine.

On macOS

If you use Homebrew or standard installers, your JDK runtimes are stored under the virtual machine path. You can list all installed environments by running:
/usr/libexec/java_home -V

Copy the path to the required version. It will look similar to this:
/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home

On Windows

By default, standard Java installers or Android Studio bundle their JDK environments inside program directories. Check these common locations:

C:\Program Files\Java\jdk-17\
C:\Program Files\Android\Android Studio\jbr\ (Android Studio's embedded Java runtime)

Step 2: Apply the Explicit Project Override (Recommended)

Instead of fighting global system environment variables that might break older projects on your machine, you can force this specific React Native project to use the correct runtime directory.

Navigate to your project's native android folder: cd android
Open the gradle.properties file.
Add the following property at the bottom, supplying the absolute path you copied in Step 1:

org.gradle.java.home=/Insert/Your/Actual/Target/JDK/Path/Here

(Note: Windows users must escape backslashes in this file, format it like: C:\\Program Files\\Java\\jdk-17)

Step 3: Align Android Studio with Your Terminal

A massive source of frustration is when the project builds fine in the terminal via CLI, but crashes the second you open it in Android Studio (or vice versa). You must align the IDE's build path:

Open your project folder inside Android Studio.
Navigate to Settings (or Preferences on macOS) > Build, Execution, Deployment > Build Tools > Gradle.
Locate the Gradle JDK dropdown menu.
Change it from the default system runtime to match the exact version your project requires (e.g., JDK 17 or JDK 21).
Click Apply and hit Sync Project with Gradle Files.

Step 4: Clear the Aggressive Build Cache

Gradle caches compilation footprints deeply. If you change your Java version without clearing the cache, Gradle will try to read the old, mismatched class files and throw the same error again.

Wipe the execution deck completely by running these commands in your root directory:

Clean the native android directories

cd android
./gradlew clean

Return to root and clear bundler caches

cd ..
npx react-native start --clear

Once the development server reboots and paths match up seamlessly across your terminal, properties file, and IDE, run your run command (npx react-native run-android or npx expo run:android) and the version mismatch error will be gone.

Fixing Gradle TLS handshake_failure on Maven Central (Android Builds)

Tue, 02 Jun 2026 15:56:09 +0000

If your Android native build is constantly failing with a TLS handshake error when trying to download dependencies from Maven Central, the root cause might be an invisible environment variable polluting your Java settings.

The most frustrating part of this error is that your local internet connection is usually completely fine.

The Quick Diagnosis

Open your terminal and test the connection directly to the Maven repository using curl:

curl -I https://repo1.maven.org/maven2/

If curl connects successfully and returns an HTTP 200, but your Gradle build still throws a Received fatal alert: handshake_failure, your network is not the problem. Gradle itself is failing to establish the secure line.

The Root Cause

An environment variable called GRADLE_OPTS is likely injecting broken SSL or JSSE flags into your build process. Specifically, flags like -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT force Gradle to look at system-specific certificate stores that conflict with standard Java behavior, breaking the handshake completely.

The Fix

To resolve this permanently, you need to wipe out the polluted configuration so Gradle can fall back to its clean JDK defaults.

Open your system Environment Variables settings.
Check both the User variables and the System/Machine variables.
Look for GRADLE_OPTS.
Delete the variable entirely from both locations.
Close your IDE, restart your terminal, and run your build again.

Once those injected flags are gone, Gradle will use standard JDK defaults, and your dependency downloads will start succeeding immediately.

I've been spending a lot of my spare time building out a diagnostic tool over at FixMyError to map out environment bugs like this automatically. I just put a live, free sandbox preview on the homepage if you want to see how the engine breaks down terminal stack traces before you ever make an account.

How to fix "Gradle build daemon disappeared unexpectedly" in React Native & Expo

Mon, 25 May 2026 10:18:22 +0000

If you’ve been building mobile apps with React Native or Expo long enough, you’ve definitely hit that brick wall where a standard debug build works perfectly, but the moment you run eas build or try to compile a production AAB/APK for the Play Store, the terminal throws a generic, frustrating crash:

"Gradle build daemon disappeared unexpectedly (it may have been killed or may have crashed)"

What makes this error so frustrating is that the terminal output rarely tells you why the daemon vanished.

The Root Cause: Out-of-Memory (OOM)

When you trigger a release build, the Node process responsible for bundling your JavaScript files, assets, and third-party native modules spikes heavily in memory. By default, Android's JVM (Java Virtual Machine) doesn't allocate enough heap space to handle these massive compilation steps for modern, dependency-heavy apps.

When the local or CI machine hits its limit, it forcefully kills the Gradle daemon to protect system stability.

The 3-Step Surgical Fix

Instead of blindly deleting your .gradle cache or reinstalling Android Studio, you can resolve this permanently by updating your configuration parameters.

1. Allocate More Heap Space

Navigate to your project's android/gradle.properties file and look for or append the org.gradle.jvmargs line. Increase the maximum heap size (-Xmx) to at least 4GB or 8GB depending on your app size:

org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:MaxPermSize=2048m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

2. Configure EAS Build (If using Expo)

If you are running your builds via Expo Application Services (EAS), you need to tell the remote builders to utilize a larger resource class. Open your eas.json file and specify a larger builder instance under your production profile:

{
  "build": {
    "production": {
      "android": {
        "resourceClass": "large"
      }
    }
  }
}

3. Clear and Reset

Once the files are saved, kill any lingering zombie daemons and clear the old build artifacts so Gradle can start fresh:

cd android
./gradlew clean
./gradlew cleanBuildCache

Taming the rest of your terminal logs

Native Android and iOS build logs can easily stretch to hundreds of lines of total noise, hiding the true dependency mismatch.

If you are currently fighting a different native module error or a breaking CocoaPods mismatch, I built a free developer utility called FixMyError that parses raw terminal dumps instantly. It strips out the conversational AI fluff and gives you the exact surgical terminal command or config change needed to unblock your build layout in 3 seconds.

Give it a spin if you are currently stuck: Try FixMyError Free

Let me know in the comments if increasing the JVM heap size successfully unblocked your production build!

Kotlin Gradle Plugin Errors: KAPT vs KSP Issues

Wed, 20 May 2026 21:21:12 +0000

Why Kotlin Gradle Plugin Build Fails (Real Errors Developers Face)

If your Kotlin project suddenly stops building after a plugin update, fails only on iOS, or breaks after gradle clean — you're not alone. These are common issues with the Kotlin Gradle Plugin that are rarely explained clearly.

This guide breaks down real-world problems like kotlin multiplatform build fails, kapt vs ksp issues, and gradle cache causing build errors.

Kotlin Multiplatform Build Fails on iOS but Works on JVM

One of the most frequent issues: your code compiles perfectly for JVM, but crashes or fails on iOS.

kotlin multiplatform iosArm64 unresolved references

This usually happens because of missing or broken native metadata. The JVM target is more forgiving, but iOS requires strict dependency resolution.

kotlin {
    iosArm64()
    sourceSets {
        val iosMain by getting {
            dependsOn(commonMain)
        }
    }
}

If your dependsOn graph is wrong, you'll get unresolved references even if the code is valid.

expect actual mismatch kotlin multiplatform error

Another common failure comes from mismatched expect/actual declarations after a compiler or plugin update.

Even a small signature change can break the build:

// commonMain
expect fun platformName(): String

// iosMain
actual fun platformName(): String = "iOS"

If types or modifiers differ — build fails silently or throws cryptic errors.

KAPT vs KSP Issues in Kotlin (Annotation Processing Problems)

Mixing kapt and ksp in one project is a classic source of instability.

kapt not working after kotlin update

KAPT often breaks after Kotlin version changes because it relies on internal compiler APIs.

Typical symptoms:

Annotation processors not running
Generated code missing
Random build failures

ksp vs kapt performance and stability

KSP is faster and more stable, but not all libraries support it. If you're mixing both, you can get conflicting generated sources.

plugins {
    id("com.google.devtools.ksp")
    kotlin("kapt")
}

This setup often leads to non-deterministic builds.

Gradle Cache Issues Causing Kotlin Build Failures

Sometimes your code is fine — but Gradle cache is not.

gradle cache causing build errors kotlin

Gradle may reuse stale compiled artifacts, especially after plugin updates.

That’s why builds fail only after:

gradle clean
switching branches
updating dependencies

how to fix gradle build cache issues kotlin

./gradlew clean build --no-build-cache

Or fully reset:

rm -rf ~/.gradle/caches

This forces a fresh dependency and compilation cycle.

Quick Fix Checklist for Kotlin Gradle Plugin Errors

Check sourceSets dependsOn graph
Verify expect/actual signatures
Avoid mixing kapt and ksp if possible
Clear Gradle cache after updates
Align Kotlin and plugin versions

Conclusion: Kotlin Build Errors Are Often Configuration Issues

Most Kotlin Gradle Plugin failures are not about your business logic — they come from configuration, cache, or tooling mismatches.

If you want a deeper breakdown with working configs, real fixes, and debugging steps, I explained everything here:

krun.pro

React Native Android Autolinking Issues: Common Problems and What to Check

Mon, 06 Apr 2026 16:56:36 +0000

Autolinking in React Native is supposed to simplify native module integration—but when it breaks, it can be frustrating and time-consuming to debug.

If your Android build is failing or a package isn’t being recognized, autolinking is often the root cause.

Here are the most common issues and what you should check.

1. Package not properly installed

Before diving deeper, make sure the dependency is correctly installed.

Check:

package.json includes the library
node_modules contains it
You’ve run:

npm install
# or
yarn install

If something feels off, delete and reinstall:

rm -rf node_modules
npm install

2. Missing or outdated Gradle sync

Autolinking depends on Gradle picking up native modules.

Try:

cd android
./gradlew clean

Then rebuild the project:

npx react-native run-android

3. Incorrect React Native CLI detection

Sometimes the React Native CLI doesn’t properly detect the module.

Run:

npx react-native config

Check if your dependency appears under:

dependencies
platforms.android

If it’s missing, autolinking is not working correctly.

4. Manual linking leftovers

If the project was upgraded or previously used manual linking, conflicts can occur.

Check:

MainApplication.java
settings.gradle
app/build.gradle

Remove any old manual linking entries.

5. Incompatible library version

Some libraries:

don’t support your React Native version
require additional setup

Always verify:

the library’s documentation
compatibility with your RN version

6. Android-specific configuration missing

Some packages still require manual steps.

Look for instructions like:

adding permissions in AndroidManifest.xml
modifying build.gradle
adding custom native code

Autolinking doesn’t cover everything.

7. Caching issues

React Native and Gradle caching can cause stale builds.

Try clearing everything:

watchman watch-del-all
rm -rf node_modules
rm -rf android/build
rm -rf android/app/build
npm install
cd android && ./gradlew clean

Final thoughts

Autolinking issues usually come down to:

installation problems
Gradle not syncing correctly
leftover manual configurations
version incompatibilities

Instead of guessing, go step by step through these checks—you’ll usually find the issue faster.

If you’re working a lot with React Native Android builds, you’ll notice most errors fall into a few recurring patterns like these.

Gradle build errors in React Native: what usually wastes the most time

Mon, 06 Apr 2026 16:49:16 +0000

If a React Native Android build fails and the output mentions Gradle, it is very easy to lose time in the wrong place.

The word “Gradle” is so broad that it can hide very different root causes:

version mismatches
plugin resolution failures
dependency conflicts
autolinking problems
corrupted caches
environment issues on the machine
native setup mistakes after upgrades

That is why “Gradle build error” is often less of a diagnosis and more of a category.

I’ve seen this kind of issue enough times to notice a pattern: the biggest time loss usually does not come from the bug itself. It comes from checking the wrong things first.

This is the checklist I would use to avoid that.

The first trap: treating Gradle as the actual problem

When people say “I have a Gradle error,” they usually mean one of two things:

the Android build failed somewhere inside the Gradle process
the terminal output included a Gradle task name, plugin message, or stacktrace

That does not automatically mean Gradle itself is the real root cause.

Very often, the actual issue is one of these:

React Native / AGP / Kotlin / JDK versions do not align
a plugin cannot be resolved
a native library was added but not integrated correctly
autolinking did not generate what the project expects
some Firebase / Android dependency is conflicting with another one
local machine setup is broken

So the first mental correction I make is:

Gradle is the place where the failure appears. It is not always the thing that is actually wrong.

What usually wastes the most time

1. Reading the last line instead of the first useful one

One of the most common wastes of time is staring at the bottom of the output.

The last line usually tells you that the build failed. It does not tell you why.

The useful clue is often earlier:

the first plugin that could not be found
the first unresolved dependency
the first incompatible version
the first task that failed for a concrete reason

If I want to save time, I search for the first meaningful error, not the most dramatic-looking one at the end.

2. Deleting everything before understanding the category of failure

Clearing caches can help sometimes.

But many people immediately do all of this:

delete .gradle
clean the project
reinstall node modules
reinstall Android Studio
reinstall the JDK
reboot the machine

Sometimes that works. But often it just burns time and makes the debugging less focused.

I only treat it as a cache/environment cleanup issue if the error actually points in that direction, such as:

corrupted transforms
temporary workspace move failures
stale artifacts
file locking
download/certificate issues

If the problem is really version alignment or plugin resolution, deleting everything does not solve the core issue.

3. Ignoring version compatibility across the Android toolchain

A lot of Gradle build errors in React Native are really compatibility problems between these pieces:

React Native version
Gradle wrapper version
Android Gradle Plugin version
Kotlin version
JDK version

If one of those is too old, too new, or mismatched with the others, the build can fail even if your app code is completely fine.

This is especially likely after:

upgrading React Native
copying Android config from another project
updating Firebase/native libraries
mixing Expo-related config with bare React Native setup

When the error looks structural, version alignment is one of the first things I check.

4. Looking only at dependencies and ignoring `settings.gradle`

Some failures are not about package versions at all.

They are about plugin resolution and build structure.

If the error mentions things like:

plugin not found
included build not found
configuration of the root project failed
React Native Gradle plugin issues
autolinking/setup task problems

then I go straight to:

android/settings.gradle
root build.gradle
plugin management / includeBuild setup

This matters a lot in newer React Native Android projects, where small mistakes in how the plugin is included can break the whole build.

5. Forgetting what changed last

This is one of the highest-value questions in debugging:

What changed right before the build started failing?

Examples:

added a native package
updated React Native
updated Firebase packages
changed Android config
changed Kotlin/Gradle/JDK versions
modified signing or release setup
switched Expo/native configuration

A lot of time gets wasted when the current error is treated as if it appeared randomly.

Usually it didn’t. Usually something moved.

The shortest path is often to inspect the most recent meaningful change.

6. Blaming Firebase too early when the issue is broader

If the problem started after adding or changing Firebase, it is tempting to assume the whole issue is “a Firebase bug.”

But many Firebase-related Gradle failures are really one of these:

dependency mismatch
version conflict
plugin/config issue
native setup not completed
packaging conflict
outdated Android build setup

So even when Firebase appears in the output, I still treat the build as a full Android build-chain problem until proven otherwise.

7. Treating all native modules as if they install the same way

React Native projects can get fragile when native modules accumulate.

Some libraries rely cleanly on autolinking. Others still depend on:

correct plugin setup
Android manifest changes
Gradle config
native initialization
version-specific setup steps

If the build started failing after adding a package, I do not just ask:

“Did I install it?”

I ask:

“What exact Android expectations did this package add?”

That distinction saves a lot of guessing.

8. Confusing machine/setup problems with project problems

Some Gradle errors are about the project.

Some are about the machine.

That is a major distinction.

I think “machine/setup issue” when the failure points toward things like:

missing SDK components
JDK problems
PATH/environment issues
SSL/certificate/download failures
local permissions
file locking on Windows
Gradle daemon state

If the project build files look normal but dependency downloads fail or local tools are inconsistent, I stop debugging app code and start checking the environment.

A practical mental model

When a React Native Android build fails with a Gradle-heavy error, I sort it into one of these buckets first.

Bucket 1: Build toolchain mismatch

Gradle wrapper
AGP
Kotlin
JDK
React Native version alignment

Bucket 2: Build structure / plugin resolution

settings.gradle
plugin management
includeBuild
plugin not found
autolinking structure

Bucket 3: Native dependency integration

newly added packages
Firebase native setup
Expo/native mix
Android-specific install expectations

Bucket 4: Cache / local environment

corrupted .gradle
locked files
SDK/JDK issues
SSL/download failures
local machine inconsistency

The goal is not to know the exact fix instantly.

The goal is to identify the correct category as early as possible.

What I would not do first

I would not immediately:

rewrite multiple Gradle files at once
downgrade random packages
reinstall everything on the machine
clear every cache without reason
assume the word “Gradle” is the real root cause
ignore the last meaningful project change

That usually increases noise instead of reducing it.

My practical order of checks

If I hit a React Native Android Gradle build error, this is the order I would usually follow:

find the first meaningful error in the build output
identify which category the failure belongs to
check RN / Gradle / AGP / Kotlin / JDK compatibility
inspect settings.gradle and plugin resolution if the error is structural
review the last package or config change
check native module integration expectations
only then treat it as a cache/environment cleanup problem if the error supports that direction

That order usually saves more time than any specific trick.

Final takeaway

The phrase “Gradle build error” often wastes time because it sounds more specific than it really is.

Most of the real causes fall into repeatable patterns:

version mismatch
plugin/build structure problem
native integration issue
cache/environment issue

The faster you identify the category, the faster the fix becomes possible.