What Access Failed
The repository requires authentication, but Maven did not send valid credentials for the repository <id> being used.
This is usually a target-and-identity problem, not a syntax problem. The request made it to the server, but the server did not like the credentials, permissions, or repository path attached to it.
Fix credentials and target access
Check the target and the credential together. Most of these fixes come down to using the right URL, account or token, and scope or repository permissions in the environment that actually failed.
Identify which repository URL is returning 401 (use mvn -X if needed).
Add or fix the matching <server> entry in ~/.m2/settings.xml (same <id> as the repository <id>), using the correct username/password or token.
If you use encrypted passwords, ensure ~/.m2/settings-security.xml is present and correct on the machine running Maven.
If you're in CI, provide a dedicated settings file and pass it explicitly:mvn -s /path/to/settings.xml ...
Retry the build. If it still fails, confirm the credentials work by authenticating to the repository using the same account/token outside Maven.
Manual authentication checks
Print effective settings and confirm the <server> entry exists: mvn -q help:effective-settings.
Confirm the repository <id> in your pom.xml (or parent POM) matches the <server><id> in settings.xml exactly.
If your CI uses a custom settings file, confirm it's actually being used (for example:mvn -s /path/to/settings.xml -q help:effective-settings).
Re-run with debug logs to confirm which repository URL is returning 401:mvn -X -DskipTests package
Why It Happens
Usually this comes down to missing or incorrect credentials in ~/.m2/settings.xml, repository <id> mismatch between pom.xml and settings.xml <servers>, using the wrong settings.xml (especially in CI) or not passing -s when expected, or credentials are present but expired/rotated (tokens) or require updated scopes.
Prove the Failing Environment Can Reach It
Re-run the original Maven goal and confirm artifact downloads succeed without 401 errors, and confirm the previously failing artifact now exists in ~/.m2/repository/.
How Maven uses repository credentials
This is the part worth understanding if the quick fix did not hold. It explains what Maven is trying to do at the moment the error appears.
Maven reads credentials from ~/.m2/settings.xml under <servers>.
A <server><id>...</id></server> entry must match the repository <id> used by your build (repositories/pluginRepositories/distributionManagement).
If the ids don't match (or the settings file isn't being used), Maven sends no credentials and the server responds with 401.
Examples
[ERROR] Failed to transfer file: https://repo.example.com/repository/maven-releases/... Return code is: 401, ReasonPhrase: Unauthorized.
[ERROR] Failed to transfer artifact com.example:private-lib:jar:1.0.0 from/to internal (https://repo.example.com/maven): Return code is: 401, ReasonPhrase: Unauthorized.Keep Credentials and Targets Aligned
To prevent this, use dedicated read-only tokens for CI and rotate them on a schedule, standardize repository ids across builds so <servers> mapping is consistent, and prefer a single repository manager endpoint so credentials are managed in one place.
Docs and source code
github.com/apache/maven/blob/maven-3.9.6/maven-core/src/main/java/org/apache/maven/project/DefaultProjectDependenciesResolver.java
HTTP status failures (401/403/407) are surfaced to Maven as a transfer failure message from the underlying resolver/wagon layer (e.getMessage()). - GitHub
String msg = "Could not resolve dependencies for project " + project.getId() + ": " + e.getMessage();
DependencyResolutionException dex = new DependencyResolutionException(msg, e);
dex.setResult(e.getResult());
throw dex;