English
Apple ID login troubleshooting
Bind one Apple ID per IPA Harbor container in the web UI. Credentials are stored for ipatool using the configured KEYCHAIN_PASSPHRASE. Complete 2FA when Apple prompts — do not submit codes repeatedly. Match your Apple ID’s App Store region to server egress when possible; frequent IP or region changes increase account friction.
IPA Harbor talks to the App Store through ipatool. When Apple ID sign-in fails in the web UI, it is usually ipatool / Apple upstream or egress networking—not IPA Harbor admin auth (Passkey/password). Apple’s authentication endpoints have changed several times since July 2026; below are common failures and what to try.
Before you start
Confirm requirements (memory/swap, rate limits, and so on).
In many cases, the latest uuphy/ipa-harbor image fixes login issues. Building your own image (see build_ipatool.sh) resolves most of the rest.
Datacenter egress and HTTP 301
If the server’s egress IP is in a datacenter or cloud POP, Apple edge nodes may soft-reject sign-in traffic. You may see HTTP 301.
The page may show:
sign-in request failed: apple returned no usable authentication response; try again later or from another network: unexpected response from Apple (HTTP 301): authentication redirect is missing Location (body length=162, content type="text/html", correlation ID="")Try:
- Switch to home broadband / a residential IP, or egress that better matches your Apple ID’s App Store region.
- If you cannot change egress IP: on an iPhone/iPad or Mac, route that same egress IP through a proxy and complete sign-in once there. In practice, after a successful login, signing in again from the same egress IP within a fixed time window is often allowed.
Slow sign-in
The first authentication runs SAP/Unicorn initialization. On a small VPS this can take about a minute, which is normal. You need more than 1 GB of RAM available—not exactly 1 GB on the plan.
If requirements are not met, the UI may show AUTH_LOGIN_SAP_INIT_FAILED (ipatool failed to initialize the authentication signing engine).
What to do:
- On low-memory hosts, configure swap as documented.
Another case—the page may show:
failed to initialize SAP action signer: create SAP signer: fetch SAP certificate: send SAP request: Get "https://s.mzstatic.com/sap/setupCert.plist": context deadline exceeded (Client.Timeout exceeded while awaiting headers)Recent ipatool builds download the SAP setup certificate from Apple’s CDN before Unicorn/SAP emulation and sign-in. Here the client timeout fired while waiting for response headers—the connection may be up, but headers never arrive (slow path, lossy link, or middlebox interference). Treat it as network instability toward Apple’s CDN.
Verification code does not work
The page may show:
2FA verification request failed: authentication request failed after 3 attempts (HTTP 204, 204, 204): apple returned no usable authentication response; try again later or from another network: unexpected response from Apple (HTTP 204): empty or non-plist authentication response (body length=0, content type="", correlation ID="")Reaching this step means your device did receive a code—Apple at least accepted that 2FA is required.
Try:
- Refresh the sign-in page, choose I already have a code, and enter the verification code.
- If that still fails, refresh and check whether you are already signed in. If not, enter your Apple ID and password again, leave the code field empty, keep the network stable, and sign in—Apple may push a new prompt.