gradle-doctor

Diagnose Gradle build failures, configuration-cache violations, and slow builds for Android and Kotlin projects.

Updated Jan 2, 2024
One-click install
npx skills add https://github.com/Mithrandir21/game-deals-app --skill gradle-doctor-mithrandir21
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gradle-doctor
Source: https://github.com/Mithrandir21/game-deals-app/tree/main/.claude/skills/gradle-doctor
Command: npx skills add https://github.com/Mithrandir21/game-deals-app --skill gradle-doctor-mithrandir21

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Gradle build failures are hard to debug because errors cascade, version compatibility between AGP, Kotlin, Compose Compiler, and KSP is fragile, and slow builds have many possible causes. This Skill provides a structured diagnostic process that classifies the real error and applies the correct fix without trial-and-error. ## Core Features & Use Cases - Error classification: Maps symptoms like dependency resolution failures, plugin incompatibility, configuration-cache violations, and duplicate classes to root-cause categories. - Version compatibility guidance: Covers the coupled upgrade matrix of AGP, Kotlin, Compose Compiler, and KSP, plus version catalog (libs.versions.toml) pitfalls. - Build performance tuning: Ordered steps for configuration cache, parallel execution, build caching, heap sizing, build scans, and KAPT-to-KSP migration. - Use Case: Your CI build passes but local fails with a configuration-cache error. The Skill walks you through reproducing with --stacktrace, identifying the first real error, converting task code to Provider/Property APIs, and verifying with a clean build. ## Quick Start Diagnose why my Gradle build fails with a configuration cache violation and tell me how to fix it.

Frequently Asked Questions about gradle-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a Gradle configuration cache violation?▼

Configuration cache violations usually come from tasks accessing Task.project or reading properties at execution time. Convert these to Provider and Property APIs, such as providers.gradleProperty(...), and enable the cache with org.gradle.configuration-cache=true in gradle.properties.

How do I diagnose a Gradle build failure?▼

Re-run the build with ./gradlew assembleDebug --stacktrace --info and read the first error, not the last, since Gradle cascades failures. Then classify the symptom: dependency resolution, plugin compatibility, compiler failure, or configuration cache, and apply the matching fix.

Why does my KSP build fail after a Kotlin upgrade?▼

KSP versions are tied exactly to Kotlin versions, for example KSP 1.9.22-1.0.17 only works with Kotlin 1.9.22. After upgrading Kotlin, update KSP to the matching release and verify all other Kotlin plugins like serialization and parcelize are aligned.

How do I speed up a slow Gradle build?▼

Enable configuration cache, parallel execution, and build caching in gradle.properties, then set an appropriate heap size. Use ./gradlew --scan or --profile to find bottlenecks, and migrate annotation processors from KAPT to KSP where supported.

Can I upgrade AGP and Kotlin at the same time?▼

It is not recommended. AGP, Kotlin, Compose Compiler, and KSP are coupled, so upgrading several at once makes it impossible to isolate which change broke the build. Upgrade one at a time and run the full build between each step.

When should I not use this Gradle diagnostic approach?▼

This diagnostic process is overkill for setting up a brand-new project from scratch. It is designed for diagnosing problems in an existing build, such as failures, version drift, or performance regressions, not greenfield project scaffolding.