🚨 Linux Error: passwd: Authentication token manipulation error — Cause, Fix, and Troubleshooting Guide

Summary

passwd: Authentication token manipulation error is PAM’s generic failure (PAM_AUTHTOK_ERR) when it cannot write the updated password to the token store. Despite the name, the most common real cause is not a wrong password — it is that PAM cannot write /etc/shadow because the filesystem is full, mounted read-only, or the file is immutable. Treat it as a “can’t write the shadow file” error first.

Common Symptoms

• passwd (or passwd <user> as root) prints passwd: Authentication token manipulation error and exits non-zero.
• The same error appears from chpasswd, usermod, useradd scripts, or automation that sets passwords.
• New user creation succeeds but setting the password fails.
• It affects all users, including root — a strong signal it is a filesystem/permissions problem, not credentials.

Most Likely Causes of the ‘passwd: Authentication token manipulation error’ Error

The phrase passwd: Authentication token manipulation error is PAM saying “I could not commit the new token.” In production, in order of frequency:

1. The filesystem holding /etc/shadow (usually /) is full. PAM writes a temp file (/etc/nshadow) and renames it; no free space means no write. Check this first.
2. / (or wherever /etc lives) is mounted read-only, often after an fsck error remount.
3. /etc/shadow (or /etc/passwd, /etc/gshadow) is immutable (chattr +i) — sometimes set by hardening scripts.
4. Wrong ownership/permissions or SELinux context on /etc/shadow.
5. Only then: the current password entered was wrong (non-root user changing their own password), or the account is locked/expired via PAM.

Quick Triage

# 1. Is the filesystem full? (the #1 cause)
df -h / /etc /home
# 2. Is it read-only?
mount | grep -E ' / |on / ' ; findmnt -no OPTIONS /
# 3. Is /etc/shadow immutable?
lsattr /etc/shadow
# 4. Permissions / SELinux context
ls -lZ /etc/shadow /etc/passwd

If df shows 100% on /, or mount shows ro, or lsattr shows an i flag, you have the cause without touching passwords.

Diagnostic Commands

# Full disk — no space to write the temp shadow file
df -h /
df -i /            # inodes can be exhausted even with free bytes

Use% 100% on / (bytes or inodes) explains the failure directly.

# Read-only root — PAM can't rewrite /etc/shadow
mount | grep ' / '
findmnt -no FSTYPE,OPTIONS /
dmesg | grep -iE 'remount|read-only|EXT4-fs error' | tail

A read-only remount is often the aftermath of a disk error — check dmesg.

# Immutable attribute blocks even root from writing
lsattr /etc/shadow /etc/passwd /etc/gshadow

An ----i---------e-- /etc/shadow line means the immutable bit is set.

# Ownership, mode, and SELinux label
ls -lZ /etc/shadow
# Expected (RHEL): ----------. root root system_u:object_r:shadow_t:s0 /etc/shadow  (mode 0000/0640)

# Auth trail — distinguishes filesystem vs credential failures
sudo tail -n 40 /var/log/auth.log         # Debian/Ubuntu
sudo journalctl -t passwd -t sudo --since "-10 min"   # RHEL/Rocky (systemd journal)
sudo journalctl _COMM=passwd --since "-10 min"

# Account state (only relevant if disk/RO/immutable are all clean)
sudo chage -l <user>          # expiry / locked
sudo passwd -S <user>         # L=locked, P=usable, NP=no password
getent shadow <user> | cut -d: -f1,2

Fix / Remediation

Work top-down; the destructive steps carry warnings.

1. If / is full, free space first. Even a few MB lets PAM write the temp shadow file. See No space left on device.

   sudo journalctl --vacuum-size=200M
   sudo du -xhd1 / 2>/dev/null | sort -h | tail
   # remove/rotate the offender, then retry:
   sudo passwd <user>

2. If root is read-only, remount read-write (after understanding why it went ro). See Read-only file system.

   Warning: A read-only remount often follows filesystem corruption. Investigate dmesg and run fsck on the next boot rather than blindly forcing rw on a damaged disk.

   sudo mount -o remount,rw /
   sudo passwd <user>

3. If /etc/shadow is immutable, clear the flag, change the password, then restore it if your hardening policy requires it.

   Warning: chattr -i removes a protection that may have been set deliberately. Confirm with whoever manages hardening before clearing it, and restore afterward.

   sudo chattr -i /etc/shadow /etc/passwd /etc/gshadow
   sudo passwd <user>
   sudo chattr +i /etc/shadow    # only if your policy set it originally

4. Fix ownership / permissions / SELinux context if those are wrong:

   sudo chown root:root /etc/shadow && sudo chmod 0000 /etc/shadow   # RHEL default 0000; Ubuntu uses root:shadow 0640
   sudo restorecon -v /etc/shadow   # RHEL/SELinux: reset label to shadow_t

5. Only if the filesystem is healthy, address credentials/account state: a non-root user must enter the correct current password; unlock or un-expire the account:

   sudo passwd -u <user>          # unlock
   sudo chage -M 99999 <user>     # clear forced expiry
   sudo faillock --user <user> --reset    # RHEL/Rocky: clear lockout
   sudo pam_tally2 --user <user> --reset   # older RHEL/Debian

Validation

# Filesystem is writable and has space
df -h / && findmnt -no OPTIONS / | grep -q rw && echo "rw+space OK"
# /etc/shadow is mutable with correct attrs
lsattr /etc/shadow
# A real password set now succeeds non-interactively
echo 'testuser:S0meTempPass!' | sudo chpasswd && echo "passwd write OK"

A successful chpasswd (or interactive passwd) with exit code 0 confirms PAM can write the token store again.

Prevention

• Monitor free space and inodes on / and alert at ~85% — a full root filesystem breaks far more than passwd.
• Keep /var/log and /var/lib from filling / by giving them their own volume or aggressive log rotation.
• If your hardening sets chattr +i on /etc/shadow, document it and wrap password changes so automation clears/restores the flag.
• Manage users and their password/expiry policy through config management (Ansible user/ansible.builtin.user) so state is reproducible.
• On RHEL, keep SELinux enforcing and run restorecon in your build so /etc/shadow always has shadow_t.

Related Errors

• Linux Error: No space left on device
• Linux Error: Read-only file system
• Linux Error: su: Authentication failure
• Linux Error: Operation not permitted
• Linux Error: Permission denied

Final Notes

passwd: Authentication token manipulation error is PAM failing to write the new password, not usually a bad password. Check for a full disk, a read-only root, and an immutable /etc/shadow before you ever suspect credentials. Fix the filesystem, and the error disappears — then, and only then, look at account locks or the current password.

Want faster Linux incident response? Use DevOps AI Toolkit to turn production errors into clear diagnostics, remediation steps, and reusable runbooks.