fix(auth): handle HTTP 421 on validate without full re-login - #489
Open
amlucas0xff wants to merge 3 commits into
Open
fix(auth): handle HTTP 421 on validate without full re-login#489amlucas0xff wants to merge 3 commits into
amlucas0xff wants to merge 3 commits into
Conversation
added 3 commits
March 8, 2026 16:29
Apple's setup.icloud.com/validate returns HTTP 421 (Misdirected Request) for connections from non-Apple networks (all Linux users). This is caused by HTTP/2 connection coalescing on Apple's CDN — not a real authentication failure. Previously, pyicloud treated 421 as an invalid session token and triggered a full re-login via idmsa.apple.com. That endpoint then returns 503 (rate-limiting), causing PyiCloudFailedLoginException even when the session_token and trust_token were perfectly valid. The result: iCloud Drive FUSE mounts and any automated Linux use of pyicloud were completely broken. The fix: when authenticate() receives 421 from _validate_token(), fall through to _authenticate_with_token() which posts the existing session_token + trust_token directly to /accountLogin. This succeeds without a password or 2FA prompt, and avoids hitting the auth rate limit. Verified working on Arch Linux (kernel 6.18, Python 3.14) with pyicloud 1.0.0 and the iCloudDriveFuse FUSE driver.
Two additions: 1. "Known Issues & Fixes" section explaining the HTTP 421 Misdirected Request problem affecting all Linux users, its root cause (Apple HTTP/2 coalescing), and how the fix works. 2. "Mounting iCloud Drive on Linux (FUSE)" section with a complete step-by-step guide covering package installation, pyicloud authentication, persistent cookie storage, iCloudDriveFuse setup, systemd auto-mount service, and token renewal maintenance. This addresses a gap in the documentation that has left Linux users unable to use pyicloud reliably without understanding the 421 behavior.
Linux users hitting the 421 error have no indication the project has a known fix. Added a callout note at the top of the README pointing directly to the Known Issues section and the FUSE mount guide, so they find the solution immediately.
|
I believe this project has been taken over by this repository: https://github.com/timlaing/pyicloud |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
All Linux users (and any non-Apple network) get a
PyiCloudFailedLoginExceptiondespite having a valid session. The failure chain is:authenticate()calls_validate_token()→POST /setup/ws/1/validateidmsa.apple.comidmsa.apple.comreturns HTTP 503 (rate-limiting repeated non-Apple logins)PyiCloudFailedLoginExceptioneven thoughsession_tokenandtrust_tokenare validThis breaks any automated Linux usage of pyicloud: FUSE drive mounts, home automation, scripts, etc.
Fix
In
authenticate(), when_validate_token()raises a 421 exception, fall through to_authenticate_with_token()instead of triggering a full password re-login._authenticate_with_token()posts the existingsession_token+trust_tokento/accountLogindirectly. This:idmsa.apple.com(avoids rate-limiting)If
_authenticate_with_token()also fails, we fall through to the original full re-login path as a last resort.Verification
Tested on:
~/iCloudBefore fix: every mount attempt failed with
Authentication required for Account. (421)→Service Temporarily Unavailable (503).After fix: authentication completes via token re-auth, drive mounts and lists files correctly.
Related issues
Relates to #330, #441 (421 authentication errors reported by Linux users)