Gradle Offline Mode: error causes and how to enable

What Does the Gradle Offline Mode Error Mean

The Gradle Offline Mode error occurs when Android Studio is running in offline mode, but Gradle cannot find the required dependencies in the local cache. As a result, the project build fails with a message similar to:

Could not resolve all files for configuration ':app:debugRuntimeClasspath'.
> Could not find com.android.tools.build:gradle:8.2.0.
  Required by:
      project :app

This mode is useful for working without an internet connection, but it requires that all artifacts (libraries, plugins) have been pre-downloaded. The error appears when you first run a new project, after clearing the cache, or when changing dependency versions.

Causes

1. Offline mode is enabled in Gradle settings — Gradle ignores online repositories and looks for artifacts only in the local cache.
2. Missing cached dependencies — for example, after installing Android Studio or when using a new computer.
3. Corrupted local Gradle cache — files in the cache (~/.gradle/caches) are damaged or incomplete.
4. Dependency version conflict — build.gradle specifies a library version that is not present in the local cache.
5. Incorrect proxy settings — Gradle cannot connect to repositories due to a firewall block or misconfigured proxy.

Solutions

Solution 1: Disable Offline Mode

The simplest solution is to disable offline mode in Android Studio settings.

1. Open File → Settings (on macOS: Android Studio → Preferences).
2. Navigate to Build, Execution, Deployment → Gradle.
3. Under Gradle settings, uncheck Offline work.
4. Click OK.
5. Sync the project by clicking Sync Project with Gradle Files (the elephant icon in the toolbar).

After this, Gradle will be able to download missing dependencies from the internet.

Solution 2: Force Project Sync

If disabling the mode didn't help, perform a forced sync with a cleanup of previous configurations.

1. Ensure Offline Mode is disabled (see Solution 1).
2. Close the project (File → Close Project).
3. Delete the .gradle folder in your project's root directory (it will be recreated).
4. Reopen the project.
5. Click Sync Project with Gradle Files.
6. Wait for the dependencies to finish downloading.

⚠️ Important: Deleting the .gradle folder in the project does not affect the global cache (~/.gradle), so it won't harm other projects.

Solution 3: Clear the Global Gradle Cache

Sometimes the issue lies in a corrupted global cache. Clearing it will force Gradle to re-download all dependencies.

1. Close Android Studio.
2. Open a terminal (cmd, PowerShell, or Bash).
3. Run the command:

   gradle --stop
   rm -rf ~/.gradle/caches/
   

   For Windows, use:

   gradle --stop
   rd /s /q %USERPROFILE%\.gradle\caches
   

4. Restart Android Studio.
5. Open the project and sync it.

💡 Tip: If you have multiple projects, they will start downloading dependencies again, which will take time depending on your internet speed.

Solution 4: Check Proxy and Network Settings

Gradle may fail to connect to repositories due to network or proxy issues.

1. Check your internet connection — open a browser and visit https://repo.maven.apache.org.
2. In Android Studio, open File → Settings → Appearance & Behavior → System Settings → HTTP Proxy.
3. Select No proxy (if on a local network) or enter correct proxy parameters.
4. Click Check connection and enter https://repo.maven.apache.org — you should see "Connection successful".
5. If using a corporate proxy, ensure settings are specified in gradle.properties (in the ~/.gradle/ folder or project):

   systemProp.http.proxyHost=your_proxy
   systemProp.http.proxyPort=port
   systemProp.https.proxyHost=your_proxy
   systemProp.https.proxyPort=port
   

6. Restart Android Studio and sync the project.

Solution 5: Update Gradle and Android Gradle Plugin

Outdated versions of Gradle or AGP may malfunction with offline mode.

1. Open the build.gradle file (Project level).
2. Check the versions:

   dependencies {
       classpath 'com.android.tools.build:gradle:8.2.0' // AGP version
   }
   

3. In the gradle/wrapper/gradle-wrapper.properties file, specify the current Gradle version:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
   

4. Sync the project — Android Studio will prompt you to update if necessary.
5. After updating, try building again.

Prevention

• Do not enable Offline Mode unless necessary — keep it disabled so Gradle can automatically update dependencies.
• Regularly update dependencies — use current library versions in build.gradle to avoid conflicts.
• Use a stable internet connection — when working with new projects, ensure you have network access.
• Do not manually delete files from the Gradle cache — this can cause corruption. Use Android Studio commands or settings for cleanup.
• Configure caching in a corporate network — if you're a developer at a company, ask your administrator to set up a local repository (Nexus, Artifactory) to reduce reliance on the internet.

These measures will help prevent the Gradle Offline Mode error from recurring and ensure stable project builds.