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

What this error means

passwd (through pam_unix) could not write the new password hash into /etc/shadow. The “token” is the password record, and “manipulation error” means the update to the backing store failed — usually because the filesystem is read-only, the shadow file is missing/immutable, the disk is full, or the account is managed elsewhere.

passwd: Authentication token manipulation error
passwd: password unchanged

The same error surfaces when changing your own password interactively or when a hardening/rotation script tries to set one non-interactively.

Where it surfaces

• passwd user (or self) ends with Authentication token manipulation error and no change.
• chpasswd in a provisioning script fails for one or more accounts.
• It started after mounting / read-only, a disk-full event, or a hardening step that set immutable bits.
• Local users fail while directory-backed users are unaffected (or vice versa).

Identity and permission causes

• Read-only filesystem. / or /etc is mounted read-only, so /etc/shadow cannot be rewritten.
• Immutable shadow. /etc/shadow carries the +i attribute from a hardening step.
• Disk full / no inodes. The write to /etc/shadow (via a temp file) cannot complete.
• Missing or corrupt shadow entry. The user has no /etc/shadow line, or it has the wrong field count.
• Network-managed account. The user comes from LDAP/AD; local passwd cannot update the directory.

Tracing the failed authorization

# Is the filesystem writable?
mount | grep -E ' / | /etc '
touch /etc/.passwd_write_test 2>&1 && sudo rm -f /etc/.passwd_write_test

# Is shadow immutable or missing an entry?
lsattr /etc/shadow 2>/dev/null
sudo getent shadow appuser        # empty => no local shadow record

# Disk / inode pressure?
df -h /; df -i /

# Where does the account come from?
getent passwd appuser

----i--------e-- from lsattr means immutable; a read-only mount or a full disk shows up in mount/df.

Resolution

1. Remount writable if / or /etc is read-only (then investigate why it went RO):

sudo mount -o remount,rw /
sudo passwd appuser

2. Clear an immutable bit set by hardening, change the password, and re-apply if your policy requires:

sudo lsattr /etc/shadow
sudo chattr -i /etc/shadow
sudo passwd appuser
# sudo chattr +i /etc/shadow    # only if your baseline expects it

3. Free space / regenerate shadow for disk or missing-entry cases:

df -h /                # clear space if full
sudo pwck             # check passwd/shadow consistency
sudo pwconv           # rebuild /etc/shadow entries where missing

4. For a network account, change the password in the directory (via kpasswd, ldappasswd, or AD tooling) — local passwd cannot.

Hardening access

• Do not hand-edit /etc/shadow; use passwd/chpasswd/pwconv to avoid corrupting field counts.
• If a hardening baseline sets +i on shadow, document it — every password change will otherwise fail mysteriously.
• A read-only rootfs is often intentional (immutable infra); change the source image/policy rather than fighting it at runtime.
• In scripts, prefer chpasswd with hashed input from a secret store over echoing plaintext passwords.

Related identity errors

• chage ‘cannot change to shadow password aging’ Error Guide
• PAM ‘authentication failure’ Error Guide
• Auditing PAM and Password Policy with AI