Question 1

How to fix CERTIFICATE_VERIFY_FAILED error during Apple ID login with xtool on Linux?

Accepted Answer

The error occurs because `gsd.apple.com` (used in the login flow) serves a certificate chain ending at **Apple Root CA - G3**, which is not included in Ubuntu's `ca-certificates` bundle (macOS trusts it via the system keychain, so the issue is Linux-only). xtool's `Client.tlsConfiguration` only added the 2006 Apple Root CA to `additionalTrustRoots`.

**Fix:** Add Apple Root CA - G3 to the trusted roots in `Sources/XKit/HTTPClientProtocol/AsyncHTTPClient+HTTP.swift`:

```swift
// gsd.apple.com chains to Apple Root CA - G3 (not the 2006 Apple Root CA).
// swiftlint:disable:next force_try
let appleRootG3CA = try! NIOSSLCertificate(bytes: Array(appleRootG3PEM.utf8), format: .pem)
tlsConfiguration.additionalTrustRoots = [.certificates([appleRootCA, appleRootG3CA])]
```

Download the certificate from https://www.apple.com/certificateauthority/AppleRootCA-G3.cer and embed it as a `private let appleRootG3PEM = """ ... """` constant. Verify the SHA-256 fingerprint: `63:34:3A:BF:B8:9A:6A:03:EB:B5:7E:9B:3F:5F:A7:BE:7C:4F:5C:75:6F:30:17:B3:A8:C4:88:C3:65:3E:91:79`.

**Verify the fix:**
```bash
openssl s_client -connect gsd.apple.com:443 -servername gsd.apple.com -CAfile AppleRootCA-G3.pem
# Should report: Verify return code: 0 (ok)
```

After rebuilding, login proceeds past the TLS handshake (a fake account now gets rejected with `-20101` instead of the handshake error, and real Apple ID login succeeds).

Question 2

How to fix 'Error: Key is invalid: invalidPEMDocument' during xtool setup?

Accepted Answer

This error occurs when you provide the wrong file path during authentication. After entering your Key ID and Issuer ID, xtool asks for the path to your `AuthKey.p8` file (downloaded from App Store Connect) — not the `Xcode.xip` file. If you mistakenly pass the Xcode.xip path, you get `invalidPEMDocument` because it is not a valid PEM/AuthKey file. Fix: run setup again and provide the full path to `AuthKey_XXXXXXXXXX.p8` when prompted for the key. You will be asked for the `Xcode.xip` path separately, after authentication completes.

Question 3

How to fix 'unknown architecture' and 'undefined symbol: main' linker errors when building with the Xcode 27 / iOS 27 SDK on Linux?

Accepted Answer

The bundled LLD 20 linker cannot parse the `arm64e.x1-ios` target declared in the iOS 27 SDK's `.tbd` stubs, so it fails to parse `libSystem.tbd` and then misleadingly reports `undefined symbol: main` — your code is fine. **Proper fix:** update xtool — this is fixed upstream via PR #270, which pulls the LLVM patch (llvm/llvm-project#222721) into darwin-tools-linux-llvm, and re-run `xtool sdk install`. **Workaround for xtool ≤1.20.0:** strip the unrecognized target from all 675 `.tbd` files in the SDK, then rebuild: `grep -rl 'arm64e\.x1-ios' "$SDK_ROOT" | while read -r f; do sed -i 's/, *arm64e\.x1-ios//g; s/arm64e\.x1-ios, *//g; s/arm64e\.x1-ios//g' "$f"; done`. Note this edit must be re-applied after every `xtool sdk install`. Substituting the Swift toolchain's LLD 21 does not work (`This version of lld does not support linking for platform iOS`).

Question 4

How to fix HTTP 503 error from GsService2 when running xtool auth login with password?

Accepted Answer

This is a known bug in xtool v1.23.0 and earlier, where Apple's edge servers reject the login request based on client-identification headers before credentials are evaluated. The fix was shipped in xtool v1.24.0 (via PR #406). Upgrade xtool to v1.24.0 or later and run `xtool auth login` again. Note: this 503 error is unrelated to the anisette server or your network/credentials — upgrading is the only fix.

Question 5

How to fix 'arm_neon.h __builtin_bit_cast source type int does not match int64_t' error when building with xtool on Linux?

Accepted Answer

This happens because `xtool sdk install` copies Clang resource headers from the `clang` found on PATH (e.g., Clang 22), while your Swift toolchain embeds an older Clang (Swift 6.4 embeds Clang 21). The mismatched headers break compilation. Workaround: replace the SDK's resource headers with ones matching Swift's embedded Clang version. For Swift 6.4 (Clang 21), install `clang21` (e.g., on Arch: `pacman -S clang21`, provides 21.1.8) and copy its headers over the installed SDK include directory: copy `/usr/lib/llvm21/lib/clang/21/include` to replace the contents of the SDK's `usr/lib/clang/21/include`. After this, the `arm_neon.h`/`_Builtin_intrinsics` errors disappear and the build proceeds. To check which Clang your Swift embeds, look for `libclang.so.21.0.0` in the toolchain. Long-term, xtool should use the toolchain's own headers or fail with a version-mismatch error (tracked in issue #273).

xtool

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects