skip to content

When and how would you use Maven's offline mode, and what are its prerequisites and pitfalls?

level: middleimportance: should knowfreq 35%

answer

  1. -o / --offline
  2. local cache only
  3. warm cache first (go-offline)
  4. go-offline misses some plugins
  5. snapshots frozen offline

basics

~20 s

Offline mode (mvn -o or --offline) tells Maven not to contact any remote repository and to build using only what's already in the local ~/.m2 cache. It's useful with no internet, but fails if anything needed isn't cached yet.

solid answer

~40 s

Offline mode (`-o`/`--offline`, or `<offline>true</offline>` in `settings.xml`) makes Maven resolve dependencies and plugins exclusively from the local repository, never touching remotes. It's used for air-gapped/CI environments, reproducible builds, or just working without a network. The prerequisite is a fully warmed cache: every dependency, plugin, and their metadata must already be present, including transitive ones. The standard way to pre-populate is `mvn dependency:go-offline` (and often running the real build once online). Pitfalls: `go-offline` doesn't always capture every plugin or extension a build truly needs (some are resolved lazily), so offline builds can still fail with "not found in offline mode." SNAPSHOTs won't update offline. The most robust approach for true reproducibility is an isolated `-Dmaven.repo.local` populated deliberately, or a controlled internal repository mirror.

code

bash · 3 lines
bash
mvn dependency:go-offline   # pre-fetch into ~/.m2
mvn -o clean install        # build with no network
# or permanently: settings.xml -> <offline>true</offline>

go deeper

for a junior

Know -o means build from the local cache with no network.

for a middle

Pre-warm with go-offline / a full online build; know snapshots freeze.

for a senior

Recognize go-offline gaps and prefer isolated maven.repo.local for reproducibility.

for a principal

Architect air-gapped/reproducible builds via controlled mirrors and seeded repositories rather than fragile literal offline.

## What offline mode does `mvn -o` (long form `--offline`) instructs Maven to **never contact remote repositories**. All dependencies, plugins, and metadata are resolved from the local repository (`~/.m2/repository`) only. You can also set it permanently with `<offline>true</offline>` in `settings.xml`. ## Why you'd use it - **Air-gapped / secure** build environments with no internet. - **Reproducibility**: guarantee the build uses exactly the cached artifacts, with no surprise updates. - **Speed / flaky network**: skip remote checks entirely. - **Avoiding accidental snapshot drift** during a release. ## Prerequisite: a warm cache Offline only works if everything the build touches is already local — including transitive dependencies, plugins, plugin dependencies, and metadata. Pre-populate it: ```bash # Try to download everything needed up front mvn dependency:go-offline # More reliable: actually run the build once while online mvn clean verify # ...then later mvn -o clean verify ``` ## Pitfalls - **Incomplete pre-fetch**: `dependency:go-offline` does not reliably fetch *every* plugin or build extension; some are resolved only when a specific goal runs. The result is the dreaded `Cannot access ... in offline mode` failure. - **SNAPSHOTs frozen**: offline means no snapshot updates, even with `-U` (which is ignored offline). - **Hidden network needs**: things like the `maven-metadata.xml` refresh or version-range resolution may want the network. - **Per-user cache drift**: "works offline on my machine" may not hold on a clean CI agent. ## More robust alternatives - Use an isolated local repo: `-Dmaven.repo.local=$PWD/.m2-ci`, populated deliberately, so the build is self-contained and reproducible. - Front everything with an internal repository manager (Nexus/Artifactory) acting as a controlled mirror — often preferable to literal offline mode for teams. ## Quick reference ```bash mvn -o clean install # one-off offline build mvn --offline -o dependency:tree # settings.xml: <offline>true</offline> for a permanent switch ```

  • Why might `mvn dependency:go-offline` still leave an offline build broken?
    It doesn't reliably resolve every plugin/extension or all lazily-resolved goals, so a needed artifact can be missing and the offline build fails with a not-found-in-offline-mode error.
  • Does `-U` do anything in offline mode?
    No. Offline mode forbids remote access, so the snapshot-update flag is effectively ignored; snapshots stay frozen at whatever is cached.

saying these in an interview costs you the question

  • Thinking offline mode downloads missing artifacts as a fallback.
  • Assuming `dependency:go-offline` guarantees a complete cache.
  • Expecting snapshots to update while offline.

context

resolving links…