Android Gradle: Fix gradle sync (Unresolved references, Cache or dependencies corrupted file system...)

README.md

Gradle: Fix gradle sync / corrupted cache file system folder

What it does

• Stops Gradle daemons
• Clears ~/.gradle/caches/x.x.0
• Clears ~/.gradle/caches/jars-9
• Clears ~/.gradle/wrapper/dists/gradle-x.x.0-bin (unless you opt out)
• Optionally runs .\gradlew.bat help to verify after cleanup

Getting started

Step 1 — Kill all Gradle daemons first (they hold the file lock)

Powershell

.\gradlew.bat --stop
# Wait 5 seconds to ensure processes exit
Start-Sleep -Seconds 5
# Belt-and-suspenders: kill any surviving Java daemon processes
Get-Process -Name "java" -ErrorAction SilentlyContinue | Stop-Process -Force

Shellscript

.\gradlew --stop
# Wait 5 seconds to ensure processes exit, and then run the command below to find any "java" process alive
ps -aux | grep "java"

Step 2 — Manually delete the journal

Powershell

Remove-Item "$env:USERPROFILE\.gradle\caches\journal-1" -Recurse -Force

Shellscript

rm -rf "$HOME\.gradle\caches\journal-1"

Quick usage

.\reset-gradle-cache.ps1

Safe preview first (recommended)

.\reset-gradle-cache.ps1 -DryRun -SkipGradleRun

Useful options

# Keep downloaded Gradle distribution zip/unpacked folder
.\reset-gradle-cache.ps1 -KeepWrapperDist

# Also clear configuration cache
.\reset-gradle-cache.ps1 -ClearConfigCache

# Use a custom repo path
.\reset-gradle-cache.ps1 -ProjectPath "C:\path\to\repo"

Next time Gradle sync breaks, just run this from the repo root:

.\fix-gradle-sync.ps1

It automatically runs the full reset including the configuration cache (which is the most common culprit for Kotlin DSL compilation breakage). Any extra flags you pass are forwarded — e.g.:

# Preview what it will do without touching anything
.\fix-gradle-sync.ps1 -DryRun

# Skip the verify-run at the end if you want to do it manually
.\fix-gradle-sync.ps1 -SkipGradleRun

fix-gradle-sync.ps1

# Convenience wrapper - resets the Gradle caches and verifies the build succeeds.
# See reset-gradle-cache.ps1 for full options.
& (Join-Path $PSScriptRoot "reset-gradle-cache.ps1") -ClearConfigCache @args

fix-gradle-sync.sh

#!/usr/bin/env bash
set -euo pipefail

# Convenience wrapper - resets the Gradle caches and verifies the build succeeds.
# See reset-gradle-cache.sh for full options.
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"

exec bash "$script_dir/reset-gradle-cache.sh" --clear-config-cache "$@"

reset-gradle-cache.ps1

[CmdletBinding()]
param(
    [string]$ProjectPath,
    [switch]$KeepWrapperDist,
    [switch]$ClearConfigCache,
    [switch]$SkipGradleRun,
    [switch]$DryRun
)

$ErrorActionPreference = "Stop"

# Derive repo root from script location when ProjectPath is not explicitly provided.
if ([string]::IsNullOrWhiteSpace($ProjectPath)) {
    $scriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
    $ProjectPath = (Resolve-Path (Join-Path $scriptPath "..")).Path
}

function Invoke-Step {
    param(
        [Parameter(Mandatory = $true)][string]$Message,
        [Parameter(Mandatory = $true)][scriptblock]$Action
    )

    Write-Host "==> $Message"
    if ($DryRun) {
        Write-Host "    [dry-run] skipped"
        return
    }
    & $Action
}

function Get-GradleWrapperInfo {
    param(
        [Parameter(Mandatory = $true)][string]$ProjectPath
    )

    $defaultVersion = "9.5.0"
    $defaultDistribution = "bin"
    $wrapperPropertiesPath = Join-Path $ProjectPath "gradle\wrapper\gradle-wrapper.properties"

    if (-not (Test-Path $wrapperPropertiesPath)) {
        return [PSCustomObject]@{
            Version      = $defaultVersion
            Distribution = $defaultDistribution
        }
    }

    $distributionLine = Select-String -Path $wrapperPropertiesPath -Pattern '^distributionUrl=' | Select-Object -First 1
    if ($distributionLine -and $distributionLine.Line -match 'gradle-([0-9A-Za-z._-]+)-(bin|all)\.zip') {
        return [PSCustomObject]@{
            Version      = $matches[1]
            Distribution = $matches[2]
        }
    }

    return [PSCustomObject]@{
        Version      = $defaultVersion
        Distribution = $defaultDistribution
    }
}

$gradleUserHome = if ($env:GRADLE_USER_HOME) {
    $env:GRADLE_USER_HOME
} else {
    Join-Path $env:USERPROFILE ".gradle"
}

$wrapperInfo = Get-GradleWrapperInfo -ProjectPath $ProjectPath
$gradleWrapperVersion = $wrapperInfo.Version
$gradleWrapperDistribution = $wrapperInfo.Distribution
$gradleMajorVersion = (($gradleWrapperVersion -split '\.')[0] -replace '[^0-9]', '')
if ([string]::IsNullOrWhiteSpace($gradleMajorVersion)) {
    $gradleMajorVersion = "9"
}

$wrapperDistPath = Join-Path $gradleUserHome "wrapper\dists\gradle-$gradleWrapperVersion-$gradleWrapperDistribution"
$cachePaths = @(
    (Join-Path $gradleUserHome "caches\$gradleWrapperVersion"),
    (Join-Path $gradleUserHome "caches\jars-$gradleMajorVersion")
)

if ($ClearConfigCache) {
    $cachePaths += (Join-Path $gradleUserHome "configuration-cache")
}

Write-Host "ProjectPath     : $ProjectPath"
Write-Host "GradleUserHome  : $gradleUserHome"
Write-Host "WrapperVersion  : $gradleWrapperVersion"
Write-Host "WrapperDistType : $gradleWrapperDistribution"
Write-Host "KeepWrapperDist : $KeepWrapperDist"
Write-Host "ClearConfigCache: $ClearConfigCache"
Write-Host "SkipGradleRun   : $SkipGradleRun"
Write-Host "DryRun          : $DryRun"

Invoke-Step -Message "Stopping Gradle daemons" -Action {
    & (Join-Path $ProjectPath "gradlew.bat") --stop | Out-Host
}

foreach ($path in $cachePaths) {
    Invoke-Step -Message "Removing $path" -Action {
        if (Test-Path $path) {
            Remove-Item $path -Recurse -Force -ErrorAction Stop
        } else {
            Write-Host "    not found, skipping"
        }
    }
}

if (-not $KeepWrapperDist) {
    Invoke-Step -Message "Removing $wrapperDistPath" -Action {
        if (Test-Path $wrapperDistPath) {
            Remove-Item $wrapperDistPath -Recurse -Force -ErrorAction Stop
        } else {
            Write-Host "    not found, skipping"
        }
    }
}

if (-not $SkipGradleRun) {
    Invoke-Step -Message "Running ./gradlew.bat help" -Action {
        Push-Location $ProjectPath
        try {
            & .\gradlew.bat help | Out-Host
        }
        finally {
            Pop-Location
        }
    }
}

Write-Host "Done."

reset-gradle-cache.sh

#!/usr/bin/env bash
set -euo pipefail

print_usage() {
    cat <<'EOF'
Usage: reset-gradle-cache.sh [options]

Options:
  --project-path <path>     Override the repository root path.
  --keep-wrapper-dist       Keep the downloaded Gradle wrapper distribution.
  --clear-config-cache      Also remove the Gradle configuration cache.
  --skip-gradle-run         Skip the final './gradlew help' verification run.
  --dry-run                 Print planned actions without changing anything.
  -h, --help                Show this help text.
EOF
}

project_path=""
keep_wrapper_dist=false
clear_config_cache=false
skip_gradle_run=false
dry_run=false

while [[ $# -gt 0 ]]; do
    case "$1" in
        --project-path)
            if [[ $# -lt 2 ]]; then
                echo "Missing value for --project-path" >&2
                exit 1
            fi
            project_path="$2"
            shift 2
            ;;
        --project-path=*)
            project_path="${1#*=}"
            shift
            ;;
        --keep-wrapper-dist)
            keep_wrapper_dist=true
            shift
            ;;
        --clear-config-cache)
            clear_config_cache=true
            shift
            ;;
        --skip-gradle-run)
            skip_gradle_run=true
            shift
            ;;
        --dry-run)
            dry_run=true
            shift
            ;;
        -h|--help)
            print_usage
            exit 0
            ;;
        *)
            echo "Unknown argument: $1" >&2
            print_usage >&2
            exit 1
            ;;
    esac
done

if [[ -z "$project_path" ]]; then
    script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
    project_path="$(cd -- "$script_dir/.." && pwd -P)"
fi

invoke_step() {
    local message="$1"
    shift

    printf '==> %s\n' "$message"
    if [[ "$dry_run" == true ]]; then
        echo "    [dry-run] skipped"
        return
    fi

    "$@"
}

remove_path() {
    local target="$1"

    if [[ -e "$target" ]]; then
        rm -rf -- "$target"
    else
        echo "    not found, skipping"
    fi
}

if [[ -n "${GRADLE_USER_HOME:-}" ]]; then
    gradle_user_home="$GRADLE_USER_HOME"
else
    gradle_user_home="$HOME/.gradle"
fi

wrapper_properties="$project_path/gradle/wrapper/gradle-wrapper.properties"
gradle_wrapper_version="9.5.0"
gradle_wrapper_distribution="bin"

if [[ -f "$wrapper_properties" ]]; then
    distribution_url_line="$(grep '^distributionUrl=' "$wrapper_properties" || true)"
    if [[ "$distribution_url_line" =~ gradle-([0-9][0-9A-Za-z._-]*)-(bin|all)\.zip ]]; then
        gradle_wrapper_version="${BASH_REMATCH[1]}"
        gradle_wrapper_distribution="${BASH_REMATCH[2]}"
    fi
fi

gradle_major_version="${gradle_wrapper_version%%.*}"
gradle_major_version="${gradle_major_version//[^0-9]/}"
if [[ -z "$gradle_major_version" ]]; then
    gradle_major_version="9"
fi

wrapper_dist_path="$gradle_user_home/wrapper/dists/gradle-$gradle_wrapper_version-$gradle_wrapper_distribution"
cache_paths=(
    "$gradle_user_home/caches/$gradle_wrapper_version"
    "$gradle_user_home/caches/jars-$gradle_major_version"
)

if [[ "$clear_config_cache" == true ]]; then
    cache_paths+=("$gradle_user_home/configuration-cache")
fi

echo "ProjectPath      : $project_path"
echo "GradleUserHome   : $gradle_user_home"
echo "WrapperVersion   : $gradle_wrapper_version"
echo "WrapperDistType  : $gradle_wrapper_distribution"
echo "KeepWrapperDist  : $keep_wrapper_dist"
echo "ClearConfigCache : $clear_config_cache"
echo "SkipGradleRun    : $skip_gradle_run"
echo "DryRun           : $dry_run"

invoke_step "Stopping Gradle daemons" bash "$project_path/gradlew" --stop

for path in "${cache_paths[@]}"; do
    invoke_step "Removing $path" remove_path "$path"
done

if [[ "$keep_wrapper_dist" != true ]]; then
    invoke_step "Removing $wrapper_dist_path" remove_path "$wrapper_dist_path"
fi

if [[ "$skip_gradle_run" != true ]]; then
    invoke_step "Running ./gradlew help" bash -c 'cd -- "$1" && bash ./gradlew help' _ "$project_path"
fi

echo "Done."