Maven "Could not transfer artifact ... 401/403" - Fix Repo Auth

By Daniel Zoghalchali·Latchkey

Maven reached the private repository but was refused with a 401 (not authenticated) or 403 (authenticated, not allowed). The credentials in settings.xml are missing, wrong, or do not match the repository id.

What this error means

Resolution against a private Nexus/Artifactory fails with Could not transfer artifact ... authentication failed ... status code: 401 or 403. Public Central artifacts download fine; only the authenticated repo fails.

mvn output

[ERROR] Failed to execute goal on project app: Could not transfer artifact
com.example:lib:jar:1.4.0 from/to internal (https://nexus.example.com/repo):
authentication failed for https://nexus.example.com/repo/.../lib-1.4.0.jar,
status: 401 Unauthorized

Diagnose it: resolve the effective POM first

Maven merges parent POMs, profiles, and settings before it builds anything. The configuration causing your failure is frequently inherited or activated by a profile that is on locally and off in CI.

Terminal

# the fully resolved configuration Maven will actually use
mvn help:effective-pom | head -60

# which profiles are active here vs on your machine?
mvn help:active-profiles

# full error, offline-safe, no colour codes to confuse the log
mvn -B -e -X <goal> 2>&1 | tail -60

Common causes

Repository id does not match a <server> id

Maven binds credentials to a repo by id. If the <repository><id> in the POM is not exactly equal to a <server><id> in settings.xml, no auth is sent and the repo answers 401.

Token missing, stale, or wrong scope

The CI secret feeding settings.xml may be empty, expired, or scoped read-only when a write is attempted (403). An unauthenticated request is also a 401.

How to fix it

Write a settings.xml from CI secrets and pass it explicitly

Generate the file in the job from secrets, with the server id matching the repository id, and point Maven at it.

Terminal

cat > ./.ci/settings.xml <<'XML'
<settings>
  <servers>
    <server>
      <id>internal</id>
      <username>${env.MVN_USER}</username>
      <password>${env.MVN_TOKEN}</password>
    </server>
  </servers>
</settings>
XML
mvn -B -s ./.ci/settings.xml verify

Match ids and verify the token scope

Confirm the repository <id> in the POM equals the <server><id> in settings.xml, character for character.
For a 403 on deploy, use a write-scoped token; a read token resolves but cannot publish.
Run mvn -X to see which server entry Maven selected for the failing host.

How to prevent it

Keep repository and server ids identical, inject tokens from CI secrets at build time, and scope read vs write tokens separately.

Frequently asked questions

What causes Maven "Could not transfer artifact ... 401/403"?

There are 2 common causes: repository id does not match a <server> id and token missing, stale, or wrong scope. Maven binds credentials to a repo by id.

How do I fix Maven "Could not transfer artifact ... 401/403"?

There are 2 fixes depending on which cause you have: write a settings.xml from ci secrets and pass it explicitly and match ids and verify the token scope. Work through them in order, since the first is the most common.

What does Maven "Could not transfer artifact ... 401/403" actually mean?

Resolution against a private Nexus/Artifactory fails with Could not transfer artifact ...

How do I stop Maven "Could not transfer artifact ... 401/403" happening again?

Keep repository and server ids identical, inject tokens from CI secrets at build time, and scope read vs write tokens separately.