skip to content

When would you use dependency:purge-local-repository, and how does it relate to SNAPSHOT and corrupted-cache problems?

level: seniorimportance: should knowfreq 35%

answer

  1. delete from .m2 + re-resolve
  2. corrupted jar / checksum error
  3. stale SNAPSHOT refresh
  4. include/manualInclude to scope
  5. -U is the lighter fix first

basics

~10 s

mvn dependency:purge-local-repository deletes this project's dependencies from the local .m2 cache and re-resolves them. You use it to recover from a corrupted/partial download or to force a stale SNAPSHOT to be re-fetched fresh.

solid answer

~40 s

The `purge-local-repository` goal removes the project's resolved artifacts from the local repository and then re-resolves them, giving a clean fetch. Typical triggers: a **corrupted or truncated jar** in `.m2` (often shown by checksum errors or 'invalid LOC header'), or a **stale SNAPSHOT** you want to force-refresh. By default it re-resolves after purging; `reResolve=false` just deletes. You can scope it with `manualInclude`/`include` patterns (e.g. one groupId) instead of nuking everything, and `actTransitively` controls whether transitive deps are purged too. It's heavier-handed than the everyday fixes: `mvn -U` forces SNAPSHOT/metadata update checks against remotes, and deleting a single bad directory under `~/.m2/repository` is the surgical option. Reserve full purge for when targeted approaches don't clear the problem; it forces re-download of everything for the project and is slow.

code

bash · 1 line
bash
mvn dependency:purge-local-repository -DmanualInclude=com.example:my-lib -DactTransitively=true

go deeper

for a junior

Knows it clears project dependencies from .m2 and re-downloads them.

for a middle

Uses include/manualInclude to scope the purge and knows -U exists.

for a senior

Picks the least-invasive fix (–U, surgical delete, scoped purge) and understands SNAPSHOT cache mutability.

for a principal

Establishes cache-hygiene runbooks and CI policies for corrupted-cache and SNAPSHOT-refresh incidents across teams.

## The local repository and SNAPSHOTs Maven caches downloaded artifacts in `~/.m2/repository`. **Release** versions (e.g. `1.2.3`) are immutable and cached forever. **SNAPSHOT** versions (e.g. `1.2.3-SNAPSHOT`) are mutable development builds; Maven checks remotes for newer SNAPSHOT timestamps on an `updatePolicy` schedule (default daily). This caching is what makes stale/corrupt-cache problems possible. ## purge-local-repository `mvn dependency:purge-local-repository` **deletes the project's artifacts** from the local repo and (by default) **re-resolves** them, yielding a clean download. Key options: - `reResolve` (default true) — re-download after deleting; set false to only delete. - `actTransitively` (default true) — also purge transitive dependencies. - `include` / `manualInclude` — comma-separated `groupId:artifactId` patterns to limit the scope, e.g. `-DmanualInclude=com.example:lib`. - `snapshotsOnly` — restrict to SNAPSHOT artifacts. ## When to use it - **Corrupted cache**: a partial download leaves a broken jar; symptoms include checksum mismatch warnings, `zip END header not found`, or `invalid LOC header`. Purge forces a fresh, verified download. - **Stale SNAPSHOT**: you need the very latest SNAPSHOT and update policy / `-U` isn't giving it to you. ## Lighter alternatives first - `mvn -U` (`--update-snapshots`) — forces Maven to check remotes for updated SNAPSHOTs and metadata; the everyday refresh. - **Surgical delete**: remove just the offending directory under `~/.m2/repository/<path>` and rebuild. - Full `purge-local-repository` is the last resort because it re-downloads everything for the project. ```bash # Refresh just one library, transitive deps included mvn dependency:purge-local-repository -DmanualInclude=com.fasterxml.jackson.core:jackson-databind # Force a SNAPSHOT/metadata update without purging mvn -U clean package ``` ## Pitfalls - Purging is project-scoped and slow; don't reach for it when `-U` or a targeted delete suffices. - It won't fix problems caused by the *remote* repository serving bad artifacts.

  • What's a lighter alternative when you just need the latest SNAPSHOT?
    Run `mvn -U` (--update-snapshots), which forces Maven to re-check remotes for newer SNAPSHOT timestamps and metadata without deleting the whole cache.
  • How do you avoid purging the entire local repo for one bad artifact?
    Use -DmanualInclude (or -Dinclude) with a groupId:artifactId pattern to scope the purge, or just delete that one directory under ~/.m2/repository.
  • Why are release versions less prone to needing a purge than SNAPSHOTs?
    Releases are immutable and cached permanently; you'd only purge them for corruption. SNAPSHOTs are mutable, so stale-cache mismatches are common.

Like emptying and re-filling a pantry shelf because one can spoiled — effective but overkill if you can just toss the one bad can.

saying these in an interview costs you the question

  • Reaching for a full purge before trying -U or a targeted delete
  • Believing it can fix a bad artifact served by the remote repo
  • Thinking release versions get re-checked like SNAPSHOTs

context

resolving links…