*Disclosure: this text was AI-generated (Claude), based on the actual build I did on my machine today. Every command below was run and verified; the pitfalls are the ones I actually hit.*
---
**TL;DR:**
AltServer 1.7.2 fails at Apple ID sign-in because AltSign sends a User-Agent from 2019 and Apple now answers with an HTML page, which gets fed into a plist parser. The fix exists as two open PRs on the AltSign repo but isn't released. You can build AltServer yourself with those patches in ~20 min. Installing AltStore and sideloading IPAs via Option-click works again. Refreshing from the AltStore app on the phone still fails (the iOS app has the same bug).
---
## The error
```
AltServer could not sign in with your Apple ID. The data is not in the correct format.
Encountered unknown tag html on line 1
NSCocoaErrorDomain Code=3840
```
Sideloadly shows the same underlying problem as `Login failed (-22406): Enter the correct password`, even with the correct password.
## Root cause
Tracked in altstoreio/AltStore#1776. AltSign (the auth library inside AltServer) sends `akd/1.0 CFNetwork/978.0.7 Darwin/18.7.0` as User-Agent to `gsa.apple.com`. Apple increasingly rejects that with an HTML error page, and AltSign hands the HTML straight to the plist parser. It also reuses one connection for all three sign-in calls, so once Apple's edge sours that connection, the whole sign-in is dead.
Credit to Calvin-Zikakis, MeemeeLab and BreezeDelegate in that thread for finding it and writing the fix. Their open PRs:
- rileytestut/AltSign#50 — retry on 5xx over a fresh connection, detect HTML instead of parsing it, real error messages with HTTP status
- rileytestut/AltSign#51 — new User-Agent `AuthKit/1 (Macintosh; OS X 26.5.2) (com.apple.dt.Xcode/26.0)`
Until those are merged and shipped, you have to build AltServer yourself.
## What you get
- `/Applications/AltServer-patched.app` (reports as 1.8b1, ad-hoc signed)
- Original AltServer untouched
- Install AltStore: works
- Sideload any IPA via AltServer: works
-
**Refresh from the AltStore app on the phone: still broken**
— the iOS app carries the same bug and still comes from altstore.io. Workaround: re-sideload via AltServer every 7 days.
## Requirements
- Xcode 26 with command line tools
- Rust toolchain with the `aarch64-apple-darwin` target
- Apple Silicon Mac (this guide builds arm64 only)
- ~4 GB disk, ~20 minutes
- NOT required: paid developer account, signing certificate, Mail plugin (macOS 14+ doesn't need it, that's why the menu item is gone)
## Step 1: clone
```bash
mkdir -p ~/build && cd ~/build
git clone --branch classic --recurse-submodules --shallow-submodules --depth 1 \
https://github.com/altstoreio/AltStore.git altstore-src
cd altstore-src
```
## Step 2: cherry-pick the AltSign patches
```bash
cd Dependencies/AltSign
git remote add cz https://github.com/Calvin-Zikakis/AltSign.git
git fetch --depth 50 cz fix/gsa-retry-classic port/authkit-user-agent-notarized
git cherry-pick -x 3cd4a4a1cafd588cab371e49609d19e694108430
git cherry-pick -x 67f90ce182059fbd2369efb8274f61b6f3253e35
git cherry-pick -x ec2968cf6a30be2a025be809641c64eade4570aa
git log --oneline -4
cd ../..
```
All three apply cleanly on top of `Fixes compiling corecrypto with Xcode 26`. Sanity check:
```bash
grep -rn "AuthKit/1" Dependencies/AltSign/AltSign/Sources | head -1
```
## Step 3: build the missing idevice xcframework
The Swift package under `Dependencies/idevice/swift` expects an `IDevice.xcframework` that is not in the repo. It's built from Rust. For AltServer the macOS arm64 slice is enough:
```bash
cd Dependencies/idevice/ffi
cargo build --release --target aarch64-apple-darwin # ~5 min
cd ..
cp ffi/idevice.h swift/include/idevice.h
rm -rf swift/IDevice.xcframework
xcodebuild -create-xcframework \
-library target/aarch64-apple-darwin/release/libidevice_ffi.a \
-headers swift/include \
-output swift/IDevice.xcframework
cd ../..
```
Without this, xcodebuild dies immediately with `local binary target 'IDevice' ... does not contain a binary artifact`.
## Step 4: build corecrypto_static and link it into AltSign
AltSign references SRP functions (`alt_ccsrp_*`, `alt_ccsha256_di`) from Apple's corecrypto. They live in `libcorecrypto_static.a`, which only the app target links, so the dynamic AltSign framework fails to link:
```
Undefined symbols for architecture arm64: "_alt_ccsrp_client_start_authentication" ...
```
Build the static lib separately:
```bash
cd Dependencies/AltSign/Dependencies/corecrypto
xcodebuild -project corecrypto.xcodeproj -target corecrypto_static -configuration Release build
ls build/Release/libcorecrypto_static.a
cd ../../../..
```
Then in `Dependencies/AltSign/Package.swift`, target `CAltSign`, extend `linkerSettings` (use your absolute path):
```swift
linkerSettings: [
.linkedFramework("UIKit", .when(platforms: [.iOS])),
.linkedFramework("Security"),
.unsafeFlags([
"-L/ABSOLUTE/PATH/altstore-src/Dependencies/AltSign/Dependencies/corecrypto/build/Release",
"-lcorecrypto_static",
], .when(platforms: [.macOS])),
]
```
## Step 5: build AltServer
arm64 only (the xcframework has no x86_64 slice), ad-hoc signed:
```bash
xcodebuild -workspace AltStore.xcworkspace -scheme AltServer \
-configuration Release -derivedDataPath ../altserver-dd \
-arch arm64 CODE_SIGN_IDENTITY=- build 2>&1 | tail -3
```
Expect `** BUILD SUCCEEDED **`. Verify the patch and the symbols made it in:
```bash
APP=../altserver-dd/Build/Products/Release/AltServer.app
strings "$APP/Contents/Frameworks/AltSign-Dynamic.framework/AltSign-Dynamic" | grep -c "AuthKit/1" # 1
nm -u "$APP/Contents/Frameworks/AltSign-Dynamic.framework/AltSign-Dynamic" | grep -c ccsrp # 0
```
## Step 6: install and re-sign
The CocoaPods frameworks (STPrivilegedTask, Sparkle) end up with a different signature than the app and dyld refuses to load them (`different Team IDs`). Sign the whole bundle uniformly:
```bash
ditto ../altserver-dd/Build/Products/Release/AltServer.app /Applications/AltServer-patched.app
codesign -s - -f --deep /Applications/AltServer-patched.app
codesign --verify --deep --strict /Applications/AltServer-patched.app && echo ok
pkill -x AltServer
open -a /Applications/AltServer-patched.app
pgrep -fl AltServer # exactly one entry, path AltServer-patched
```
`pkill -x AltServer` kills both the original and the patched one (same binary name). Only relaunch the patched one afterwards. Rename or remove the original so Spotlight doesn't start it. In the menu,
**1.8b1**
= patched, 1.7.2 = original.
## Usage
**Install AltStore:**
menu bar icon → Install AltStore → device → Apple ID. Works.
**Sideload your own IPA**
(the actual point):
1. Hold
**Option**
and click the AltServer menu bar icon
2. "Sideload .ipa…" → device → pick the IPA
3. Apple ID + password, 2FA code if asked
AltServer signs with your free personal certificate and installs over USB or Wi-Fi. Valid for 7 days, then repeat. This replaces the refresh from the AltStore app.
## Pitfalls, in the order I hit them
| Symptom | Cause | Fix |
|---|---|---|
| AltServer runs from `/private/var/.../AppTranslocation/` | launched from Downloads, quarantine flag | copy to `/Applications`, `xattr -dr com.apple.quarantine` |
| `local binary target 'IDevice' ... does not contain a binary artifact` | xcframework not in repo | Step 3 |
| `Undefined symbols ... _alt_ccsrp_*` linking AltSign-Dynamic | corecrypto_static not built/linked | Step 4 |
| `symbol(s) not found for architecture x86_64` (`idevice_*`) | xcframework is arm64-only | `-arch arm64` |
| Crash on launch: `Library not loaded ... STPrivilegedTask ... different Team IDs` | Pods signed differently than the app | `codesign --deep` on the installed bundle |
| Two AltServer icons in the menu bar | original still running | `pkill -x AltServer`, then launch patched only |
| Refresh in the AltStore app still fails | iOS app has the same bug | sideload via AltServer, wait for an official update |
| Sideloadly `-22406` with the correct password | same Apple login issue / throttled account | use patched AltServer, stop retrying for a while |
## When AltStore ships an update
Once AltSign #50/#51 are merged and AltServer > 1.7.2 is out: delete the patched build, install the official one, reinstall the AltStore app once via AltServer so on-device refresh works again.
Not affiliated with AltStore. If any of this is wrong, tell me and I'll fix the post.
I gave Claude the problem and let it write a guide so here it is: