Gmail IMAP [AUTHENTICATIONFAILED] Invalid credentials is usually not a typo
Deploy and infrastructure
Symptom
imaplib login fails with [AUTHENTICATIONFAILED] Invalid credentials. You re-check the password; same result. Time lost in the same spot every time.
Cause
It's usually not a wrong password. Three causes:
- You used the account password. Gmail refuses IMAP logins with the regular password. Turn on 2-step verification and issue a 16-character app password.
- IMAP is disabled. Settings → Forwarding and POP/IMAP → Enable IMAP. Recent Gmail has it on by default and may not show the toggle at all — then this isn't your cause.
- The app password was revoked. It leaked, you reissued it, and the env file was never updated. The code keeps sending the old value.
Fix
- Store the app password as 16 characters with no spaces. The issuing screen shows it in groups of four; drop the spaces when pasting.
- When you reissue, update the env file in the same sitting. Issuing and applying is one task.
- Confirm
imap.gmail.com:993 (SSL). The STARTTLS port gives a different error.
Verification
From a shell, run one line of imaplib.IMAP4_SSL('imap.gmail.com', 993).login(...) with the exact value from the env file, not through the app's code path. Passes → the app is at fault. Fails → the credential is.
★ "Invalid credentials" more often means "not accepted this way" than "wrong value."