gradle-troubleshooting（梯度故障排除）

Gradle Troubleshooting

Table of Contents

• When to Use This Skill
• Quick Start
• Instructions
• Examples
• Commands Reference
• See Also

When to Use This Skill

Use this skill when you need to:

• Debug OutOfMemoryError or heap space issues
• Resolve dependency conflicts and version mismatches
• Fix build cache or configuration cache problems
• Diagnose slow build performance
• Troubleshoot daemon or wrapper issues
• Debug plugin loading failures
• Resolve TestContainers or Docker connectivity issues
• Investigate test failures in CI but not locally

Quick Start

When a build fails, run in order:

# 1. Stop daemon and clean
./gradlew --stop
./gradlew clean

# 2. Run with diagnostics
./gradlew build --stacktrace --info

# 3. If still failing, generate build scan
./gradlew build --scan

# 4. If slow, profile
./gradlew build --profile

Instructions

Step 1: Diagnose with Debug Output

Run with increasing verbosity to identify the issue:

# Stack trace (shows where error occurred)
./gradlew build --stacktrace

# Full stack trace (complete call stack)
./gradlew build --full-stacktrace

# Info logging (what Gradle is doing)
./gradlew build --info

# Debug logging (very detailed, generates lots of output)
./gradlew build --debug

# Use grep to filter
./gradlew build --info 2>&1 | grep -i error
./gradlew build --info 2>&1 | grep cache

Step 2: Identify the Issue Category

OutOfMemoryError:

./gradlew build 2>&1 | grep -i "outofmemory\|java heap\|metaspace"

Dependency resolution:

./gradlew dependencies --info 2>&1 | grep -i "could not\|failed\|error"
./gradlew dependencyInsight --dependency spring-core

Build cache problems:

./gradlew build --no-build-cache --info 2>&1 | grep cache

Configuration cache:

./gradlew build --no-configuration-cache --info

Plugin issues:

./gradlew build --stacktrace 2>&1 | grep -A 5 "plugin"

Step 3: Fix OutOfMemoryError

Immediate fix - Increase heap size:

# For this build only
./gradlew build -Dorg.gradle.jvmargs="-Xmx8g"

# Or stop daemon and increase persistent memory
./gradlew --stop

Permanent fix - Update gradle.properties:

# For standard projects (10-30 modules)
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# For large projects (30+ modules)
org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=2g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# For very large projects
org.gradle.jvmargs=-Xmx12g -XX:MaxMetaspaceSize=3g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

Verify fix:

./gradlew --stop  # Must restart daemon
./gradlew build --info 2>&1 | grep "XX:Xmx"

Step 4: Debug Dependency Resolution

Understand why dependencies aren't resolving:

# Show full dependency tree
./gradlew dependencies

# Show specific configuration
./gradlew dependencies --configuration implementation

# Find where a dependency comes from
./gradlew dependencyInsight --dependency spring-core

# Show dependency insights for specific config
./gradlew dependencyInsight --dependency jackson-databind --configuration implementation

# Refresh and re-download
./gradlew build --refresh-dependencies

Common solutions:

Option 1: Force specific version:

// build.gradle.kts
configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:32.1.3-jre")
    }
}

Option 2: Exclude problematic transitive dependency:

dependencies {
    implementation("com.example:library:1.0") {
        exclude(group = "commons-logging", module = "commons-logging")
    }
}

Option 3: Use dependency constraints:

dependencies {
    constraints {
        implementation("org.apache.commons:commons-lang3:3.18.0")
    }
}

Step 5: Debug Build Cache Issues

Test if build cache is causing problems:

# Disable cache for this build
./gradlew build --no-build-cache

# If this fixes it, cache is the problem
# Clean cache
rm -rf ~/.gradle/caches/build-cache-*

# Check cache status
./gradlew build --build-cache --info | grep cache

# Verify task is cacheable
./gradlew build --info 2>&1 | grep "Cache key"

Common build cache issues:

Issue: Build slower with cache enabled

# Check for non-cacheable tasks
./gradlew build --info 2>&1 | grep -i "non-cacheable"

Issue: Incorrect cached results

# Clean entire cache
rm -rf ~/.gradle/caches

# Rebuild
./gradlew build

Step 6: Debug Configuration Cache

Test if configuration cache is compatible:

# Start with warnings (not errors)
./gradlew build --configuration-cache-problems=warn

# Check report
# build/reports/configuration-cache/<hash>/configuration-cache-report.html

# Once issues fixed, enable strict mode
./gradlew build --configuration-cache-problems=fail

Common configuration cache issues:

Issue: Build fails with configuration cache

# Disable temporarily
./gradlew build --no-configuration-cache

# Check for incompatible plugins
./gradlew build --configuration-cache-problems=warn --info

# View detailed report
open build/reports/configuration-cache/report.html

Issue: Plugins not compatible

# Update plugins to latest versions
./gradlew wrapper --gradle-version 9.2
./gradlew build -x test  # Skip tests temporarily

For advanced troubleshooting including slow build analysis, daemon management, wrapper issues, and plugin resolution, see references/advanced-troubleshooting.md.

Examples

Example 1: Complete Troubleshooting Workflow

# 1. Initial failure
./gradlew build
# BUILD FAILED

# 2. Get details
./gradlew build --stacktrace
# Shows: OutOfMemoryError: Java heap space

# 3. Fix: Update gradle.properties
echo "org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g" >> gradle.properties

# 4. Stop daemon and retry
./gradlew --stop
./gradlew build

# BUILD SUCCESSFUL

Example 2: Dependency Conflict Resolution

# Build fails with version conflict
./gradlew build
# ERROR: Could not resolve dependency: conflicting versions

# Investigate
./gradlew dependencyInsight --dependency commons-lang3

# You see:
# commons-lang3:3.8.1 <- old-library
# commons-lang3:3.18.0 <- new-library

# Solution: Force newer version
# In build.gradle.kts:
configurations.all {
    resolutionStrategy {
        force("org.apache.commons:commons-lang3:3.18.0")
    }
}

./gradlew build
# BUILD SUCCESSFUL

For advanced examples including slow build analysis, configuration cache debugging, and Docker troubleshooting, see references/advanced-examples.md.

Commands Reference

See references/commands-and-checklists.md for complete command reference, troubleshooting checklist, and quick reference table.

See Also

• gradle-testing-setup - Configure testing infrastructure
• gradle-performance-optimization - Optimize build performance
• gradle-ci-cd-integration - CI/CD integration patterns
• Gradle Documentation
• Gradle Build Scans