skip to content

What changes require a re-sync in the IDE, and how do you recognize and recover from a stale Gradle model?

level: middleimportance: should knowfreq 50%

answer

  1. build script / settings / catalog edit -> re-sync
  2. deps, plugins, modules, source sets
  3. source-only edits don't need sync
  4. symptoms: red imports, missing module, stale tasks
  5. escalate: --stop, Invalidate Caches, delete derived state

basics

~20 s

Re-sync after editing build scripts, settings.gradle, version catalogs, or anything that changes dependencies, plugins, modules, or source sets. A stale model shows as wrong/missing dependencies, unresolved symbols, or modules that don't match the build. Re-sync (or refresh Gradle project) to rebuild the model.

solid answer

~50 s

The IDE model is only as fresh as the last sync. You need a **re-sync** whenever something that the model captures changes: editing `build.gradle(.kts)` or `settings.gradle(.kts)`, changing the **version catalog** (`libs.versions.toml`), adding/removing **dependencies, plugins, modules (`include`)**, or altering **source sets**. IntelliJ usually shows a 'Gradle build scripts have changed' banner with a *Load Gradle Changes*/refresh action; you can also trigger it from the Gradle tool window. **Stale-model symptoms**: a dependency you added isn't on the classpath (red imports), a new module isn't recognized, a removed dependency still resolves, generated sources aren't visible, or task list is outdated. **Recovery**: re-sync first. If that doesn't fix it (corrupted caches, plugin upgrade), escalate to *Invalidate Caches / Restart*, delete `.gradle`/`.idea` module files, or stop daemons — but those are heavier and rarely needed; a plain re-sync resolves the common cases.

go deeper

for a junior

Know that changing build files needs a re-sync and where the refresh button is.

for a middle

Enumerate which changes trigger re-sync (scripts, settings, catalog, deps, plugins, modules, source sets) and read stale-model symptoms.

for a senior

Diagnose IDE-vs-CLI classpath drift, decide between re-sync and heavier recovery, and weigh auto-import vs its configuration cost.

for a principal

Define team guidance for keeping models fresh, manage sync cost in large repos, and standardize recovery runbooks.

## The model is a snapshot A sync produces a **point-in-time model** (modules, source sets, dependencies, tasks). The IDE keeps using that snapshot until you sync again. So the core mental model is: *did I change something the model captured? Then re-sync.* ## What requires a re-sync - **Build scripts**: any edit to `build.gradle` / `build.gradle.kts`. - **Settings**: `settings.gradle(.kts)` — added/removed `include(...)`, `includeBuild(...)`, plugin management, repositories. - **Version catalog**: `gradle/libs.versions.toml` changes (versions, aliases). - **Dependencies & plugins**: adding, removing, or upgrading. - **Module structure / source sets**: new subproject, new/renamed source set, changed source/resource dirs. - **Wrapper/Gradle version** (`gradle-wrapper.properties`) or JVM toolchain changes. Merely editing application source code (`.java`/`.kt`) does **not** need a sync — only build *structure/metadata* changes do. ## Recognizing a stale model - Newly added dependency → unresolved imports / red code even though it's in the build file. - Removed dependency still resolving in the IDE. - New module/subproject not appearing. - Generated sources not on the classpath. - Outdated task list in the Gradle tool window. - 'Works on the command line, broken in IDE' for classpath reasons. ## How to re-sync - Click the **Load Gradle Changes / refresh** banner IntelliJ shows after a script edit. - Press the **refresh (reimport) button** in the Gradle tool window. - Eclipse Buildship: *Gradle → Refresh Gradle Project*. - You can enable **auto-import/auto-reload** so the IDE syncs automatically on script changes (convenient, but each sync still runs configuration). ## When re-sync isn't enough If a re-sync doesn't clear the problem: 1. **Stop Gradle daemons** / kill stuck daemon (`./gradlew --stop`). 2. **Invalidate Caches / Restart** in IntelliJ (rebuilds IDE indexes). 3. Delete derived state: project `.gradle/`, IDE module files, then re-sync/reimport. 4. After a **plugin upgrade** that changes the model, a clean re-import is sometimes required. Start with the cheapest step (plain re-sync) and escalate only if needed. ```text Edit build.gradle / settings.gradle / libs.versions.toml -> IDE banner: 'Load Gradle Changes' -> re-sync -> still broken? -> ./gradlew --stop -> Invalidate Caches/Restart -> re-import ```

  • You added a dependency to libs.versions.toml and the import is still red. First step?
    Re-sync (Load Gradle Changes / refresh the Gradle project). A catalog change updates the model only after a sync.
  • Does editing a .kt source file require a re-sync?
    No. Only build structure/metadata changes (scripts, settings, catalog, deps, modules, source sets) need a sync; ordinary source edits do not.

saying these in an interview costs you the question

  • Reaching for 'Invalidate Caches / Restart' before trying a plain re-sync.
  • Thinking every code edit needs a sync (only build/metadata changes do).

context

resolving links…