Return code is: 401, ReasonPhrase: Unauthorized

What This Error Means

The repository requires authentication, but Maven did not send valid credentials for the repository <id> being used.

How to Fix It

1. Identify which repository URL is returning 401 (use mvn -X if needed).
2. Add or fix the matching <server> entry in ~/.m2/settings.xml (same <id> as the repository <id>), using the correct username/password or token.
3. If you use encrypted passwords, ensure ~/.m2/settings-security.xml is present and correct on the machine running Maven.
4. If you're in CI, provide a dedicated settings file and pass it explicitly: mvn -s /path/to/settings.xml ....
5. Retry the build. If it still fails, confirm the credentials work by authenticating to the repository using the same account/token outside Maven.

Why It Happens

• 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.
• Credentials are present but expired/rotated (tokens) or require updated scopes.

How to Verify

1. Re-run the original Maven goal and confirm artifact downloads succeed without 401 errors.
2. Confirm the previously failing artifact now exists in ~/.m2/repository/.

Manual authentication checks

1. Print effective settings and confirm the <server> entry exists: mvn -q help:effective-settings.
2. Confirm the repository <id> in your pom.xml (or parent POM) matches the <server><id> in settings.xml exactly.
3. 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).
4. Re-run with debug logs to confirm which repository URL is returning 401: mvn -X -DskipTests package.

Common CLI Output

[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.

How Maven uses repository credentials

1. Maven reads credentials from ~/.m2/settings.xml under <servers>.
2. A <server><id>...</id></server> entry must match the repository <id> used by your build (repositories/pluginRepositories/distributionManagement).
3. If the ids don't match (or the settings file isn't being used), Maven sends no credentials and the server responds with 401.

Prevention Tips

• Use dedicated read-only tokens for CI and rotate them on a schedule.
• Standardize repository ids across builds so <servers> mapping is consistent.
• Prefer a single repository manager endpoint so credentials are managed in one place.

Where This Can Be Triggered

String msg = "Could not resolve dependencies for project " + project.getId() + ": " + e.getMessage();
DependencyResolutionException dex = new DependencyResolutionException(msg, e);
dex.setResult(e.getResult());
throw dex;