skip to content

A deploy fails with 401 Unauthorized even though credentials are encrypted in settings.xml. How do you diagnose it?

level: seniorimportance: should knowfreq 30%

answer

  1. id must match repo id
  2. settings-security.xml present?
  3. token corrupted by shell
  4. mvn -X to see decrypt
  5. help:effective-settings
  6. password expired/perms

basics

~20 s

Check that the <server> id exactly matches the repository id, that settings-security.xml exists and contains the master, that the encrypted token wasn't corrupted by shell quoting, and that the password itself is still valid on the server.

solid answer

~40 s

Work the chain end to end. First, id matching: the `<server><id>` must equal the `<repository>`/`<distributionManagement>` id Maven is hitting — a mismatch means no auth is sent (often a 401). Second, confirm `~/.m2/settings-security.xml` exists and holds a valid `<master>`; if it's missing or its master token is malformed, Maven can't decrypt the server password. Third, suspect copy-paste/shell damage to the `{...}` token (stray braces, truncation). Re-run `mvn --encrypt-password` and re-paste. Fourth, run `mvn -X deploy` and inspect debug logs to see whether decryption succeeded and which credentials/realm were used. Fifth, verify the underlying password is still valid and not expired/rotated on the server, and that the account has deploy permission. Also check you're using the intended settings file (`-s`) and not an effective-settings override — `mvn help:effective-settings` helps.

code

bash · 2 lines
bash
mvn -X deploy                                  # see decryption + matched server id
mvn -s ~/.m2/settings.xml help:effective-settings  # confirm which settings/servers apply

go deeper

for a junior

Checks that username/password are present and not obviously wrong.

for a middle

Verifies id matching and that settings-security.xml exists.

for a senior

Uses -X and effective-settings to trace the decryption and matched realm.

for a principal

Builds a repeatable triage runbook and removes whole classes of failure via CI secret injection.

## Diagnose along the credential chain A 401 with encryption in play almost always breaks at one of these links: ### 1. id mismatch (most common) Maven only sends credentials when the `<server><id>` matches the id of the repository it is contacting. A typo or a different deploy id silently sends no auth. Cross-check the id in `<distributionManagement>` (for deploy) or `<repository>` (for download) against `<servers>`. ### 2. Missing or broken master If `~/.m2/settings-security.xml` is absent or its `<master>` is malformed, Maven cannot decrypt the server password. The build may log a decryption warning or fall back to using the raw `{token}` as the literal password — which the server rejects. ### 3. Corrupted token The `{...}` token can be mangled by shell quoting, line wraps, or partial copy. Regenerate with `mvn --encrypt-password` and paste carefully. ### 4. Confirm with debug logging ```bash mvn -X deploy ``` Debug output shows the auth realm, whether decryption ran, and which server id matched — without printing the plaintext. ### 5. Wrong settings file You might be running with a different settings file than you think. Force it and inspect the merge: ```bash mvn -s ~/.m2/settings.xml help:effective-settings ``` ### 6. Server-side causes Finally, the credential itself may be expired/rotated, the account may lack deploy permission, or the repo may be a release repo refusing a SNAPSHOT (or vice versa). Those return 401/403/400 unrelated to encryption. ## Quick mental checklist id match -> master present -> token intact -> -X log -> right settings file -> account still valid.

  • Why would a correct password still yield 401 with encryption set up?
    Most often the <server> id doesn't match the repository id, so Maven sends no credentials at all.
  • How can a missing settings-security.xml cause auth failure rather than an obvious error?
    Maven may fail to decrypt and end up using the raw {token} as the literal password, which the server rejects as wrong.

saying these in an interview costs you the question

  • Assuming 401 means the password is wrong before checking the id match
  • Editing the encrypted token by hand to 'fix' quoting
  • Forgetting Maven may be reading a different settings file than expected

context

resolving links…