apache/maven · error · TransferFailedException

Failure to resolve " + remotePath + " from " + repository.ge

Error message

Failure to resolve " + remotePath + " from " + repository.getUrl() + " was cached in the local repository. Resolution will not be reattempted until the update interval of " + repository.getId() + " has elapsed or updates are forced. Original error: " + error

What it means

Thrown by the legacy DefaultWagonManager when an artifact's file does not exist locally and the update check manager has a previously recorded error for that artifact+repository. The first failed download (TransferFailedException) is cached in the resolver status files (_remote.repositories / *.lastUpdated) under ~/.m2/repository; until the repository's update interval elapses or -U forces recheck, Maven refuses to retry and rethrows the cached failure with its original error message.

Source

Thrown at compat/maven-compat/src/main/java/org/apache/maven/repository/legacy/DefaultWagonManager.java:142

                    updateCheckManager.touch(artifact, repository, null);
                } catch (ResourceDoesNotExistException e) {
                    updateCheckManager.touch(artifact, repository, null);
                    throw e;
                } catch (TransferFailedException e) {
                    String error = (e.getMessage() != null)
                            ? e.getMessage()
                            : e.getClass().getSimpleName();
                    updateCheckManager.touch(artifact, repository, error);
                    throw e;
                }

                logger.debug("  Artifact " + artifact.getId() + " resolved to " + artifact.getFile());

                artifact.setResolved(true);
            } else if (!artifact.getFile().exists()) {
                String error = updateCheckManager.getError(artifact, repository);
                if (error != null) {
                    throw new TransferFailedException("Failure to resolve " + remotePath + " from "
                            + repository.getUrl()
                            + " was cached in the local repository. "
                            + "Resolution will not be reattempted until the update interval of "
                            + repository.getId() + " has elapsed or updates are forced. Original error: " + error);

                } else {
                    throw new ResourceDoesNotExistException(
                            "Failure to resolve " + remotePath + " from " + repository.getUrl()
                                    + " was cached in the local repository. "
                                    + "Resolution will not be reattempted until the update interval of "
                                    + repository.getId() + " has elapsed or updates are forced.");
                }
            }
        }
    }

    @Override
    public void getArtifact(

View on GitHub (pinned to e4093d4e12)

Solutions

Re-run with -U (--force-update-checks) to bypass the cached failure and retry immediately
Fix the original error named after 'Original error:' (credentials, URL, proxy) - otherwise -U just re-caches it
Delete the artifact's directory under ~/.m2/repository (and its *.lastUpdated files) to clear the poisoned state
Check repository <releases>/<snapshots> updatePolicy in the POM - 'never' or long 'interval:X' keeps the cache hot; 'always' avoids this trap
In pipelines, use isolated local repos or -U for jobs that must not inherit cache state

Example fix

# before
mvn clean install
# after
mvn clean install -U
# or purge the cached state
rm -rf ~/.m2/repository/com/example/broken-artifact

Defensive patterns

Strategy: retry

Validate before calling

// Detect a poisoned cache before building
Path lastUpdated = localRepoDir.resolve("_remote.repositories");
boolean poisoned = Files.exists(lastUpdated)
    && Files.readString(lastUpdated).contains("ERROR");
if (poisoned) purgeArtifactDir(localRepoDir); // or plan to run with -U

Try / catch

catch (org.apache.maven.wagon.TransferFailedException e) {
    if (e.getMessage() != null && e.getMessage().contains("was cached in the local repository")) {
        // rerun resolution with force=true / mvn -U after fixing the original error
    }
}

Prevention

Use -U in CI jobs that must not inherit cached failures
Fix root causes (credentials/proxy) before retrying, or -U just re-caches
Use per-build local repos in pipelines
Set sensible updatePolicy (interval:60 / always) on critical repos

When it happens

Trigger: getArtifact() with force=false, updateCheckManager.isUpdateRequired()==false, artifact file missing, and updateCheckManager.getError() returning the message saved from an earlier TransferFailedException (auth failure, connection failure, checksum failure) recorded by touch(artifact, repository, error).

Common situations: The classic 'was cached in the local repository, resolution will not be reattempted' CI failure: a transient network/auth blip poisons the cache, then every rebuild replays it until -U or interval elapses; fixed credentials not picked up because the failure is remembered; Nexus down once at snapshot poll time.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/73fe44b66ad44e39. Report an issue: GitHub.