DEV Community

孫昊
孫昊

Posted on

TestFlight install fail: 30 days of debugging the Apple ID lock nobody told you about

#ios #appstoreconnect #debug #indie

dev.to article #27 (paste-ready) — TestFlight install fail: 30 days, Apple Engineering, and the Apple ID lock nobody told you about

Calendar: 2026-05-29 09:00 PT (1 week after #26)
Tags: #ios #appstoreconnect #testflight #indie #debug
Word count: 2200 (full debug story + reproducible scripts)
Cover image: 1000x420 — TestFlight icon + "30 days" countdown

TL;DR

If TestFlight installs fail with "App not available" even though build status looks healthy, the root cause is likely Apple's backend tester record lock. A tester email is permanently linked to the Apple ID that first accepted the invite — even after the tester is deleted.

This is documented in Apple Developer Forum thread 702988 but very few indie devs hit it because most use one Apple ID per dev and one per tester from day one.

I hit it after switching tester accounts. 30 days of debugging, 1 forum thread that explained it, and 4 workarounds that may or may not unlock it before the natural 90-day expiration.

Here are my notes.

What "App not available" looks like (and what it isn't)

After tapping the TestFlight invite link, the user sees one of:

"App not available
This app is not available in your country or region."
Enter fullscreen mode Exit fullscreen mode 
"App not available or does not exist."
Enter fullscreen mode Exit fullscreen mode

This is misleading. The app IS available. The build IS valid. The tester IS in the group. ASC says everything is healthy. Yet install fails.

It's NOT:

  • Your build expired (would say "Build expired")
  • Your build is invalid (would say "Build invalid")
  • Your tester isn't in the group (would say "Not a tester")
  • Your country is restricted (would say "Region not supported")

It IS:

  • Apple's backend tester→AppleID linkage permanent until 90-day build expire
  • A specific edge case when the tester email accepted invite from a different Apple ID earlier

How I got here (the boring history)

Day 0: Created sandbox tester snakesun@qq.com (linked to test Apple ID). Sent invite, accepted, installed first build.

Day 30: Switched to a different sandbox tester sh1990914@hotmail.com (linked to my real personal Apple ID). Deleted snakesun from group. Sent invite to sh1990914, accepted on iPhone.

Tap "Install" → ❌ App not available.

ASC API says:

  • Build state: IN_BETA_TESTING ✅
  • Tester record exists ✅
  • Tester sh1990914 in group ✅
  • Tester accepted invite ✅
  • Paid Apps agreement ACTIVE ✅
  • 175 territories selected ✅
  • Age rating set ✅
  • Privacy URL set ✅

Everything looked healthy. Install failed anyway.

What I tried that did NOT work

  1. DELETE+POST build cycle (Apple's recommended cache refresh): fail × 3
  2. Hard delete tester records (account-level via /v1/betaTesters DELETE not just /v1/betaGroups/{id}/relationships/betaTesters): fail
  3. Re-invite from scratch: Apple sent new email, user accepted, install still fails
  4. Re-upload binary as new build: rebuilt, same fail
  5. Submit App Store metadata for review (just to force any cache update): not needed for TF, didn't help
  6. Toggle paid agreement: pointless, was already ACTIVE
  7. Change age rating / privacy URL / category: cosmetic, doesn't affect TF install

After 30 days of trying, I stopped guessing and went to Apple Developer Forum.

The Apple Engineering answer

Forum thread 702988, Apple staff response:

"A different Apple ID previously accepted the tester invitation for that email address. A tester email can only be linked to one Apple ID at a time. Testers in the Deleted state aren't fully removed from TestFlight until their last installed build expires (typically 90 days)."

In plain English:

  • I had sh1990914 linked to my Apple ID via the failed install attempts
  • Apple backend recorded "this email belongs to "
  • When I deleted snakesun the orphan record kept the Apple ID lock
  • New invites to sh1990914 are accepted but the lock isn't released
  • Lock auto-releases when the originally-linked Apple ID's last installed build expires (90 days)

For my apps, the originally-linked build was uploaded ~Apr 28. Lock release: ~July 28.

What might work before 90 days

Forum search + Apple Discussions + Reddit r/iOSdev produced 4 workarounds:

Plan B: Apple ID region switch

Apple Discussions thread 252420194 — 625 reports of similar TF issue solved by switching iPhone Apple ID country/region.

1. iPhone Settings → Apple ID → Media & Purchases → View Account
2. Country/Region → Change Country or Region
3. Choose United States (or different from current)
4. Skip billing info (don't enter card)
5. Restart TestFlight app
6. Re-tap invite link → Install
7. After install: switch back to original region
Enter fullscreen mode Exit fullscreen mode

Works for ~60% of reports. Not 100%.

Plan C: Sign out + delete TestFlight + reinstall 

1. iPhone Settings → Apple ID → Media & Purchases → Sign Out (NOT iCloud sign out)
2. Long-press TestFlight app → Delete
3. Restart iPhone
4. App Store → reinstall TestFlight
5. Sign In Media & Purchases with the *correct* Apple ID
6. Re-tap invite link → Accept → Install
Enter fullscreen mode Exit fullscreen mode

Works for cases where the previous Apple ID linkage is on the iPhone-side, not server-side. Less reliable.

Plan D: New Apple ID for the tester email 

1. apple.com/account → Create New Apple ID
2. Use a different email (NOT the locked tester email)
3. iPhone → Sign Out current Apple ID, Sign In new Apple ID (Media & Purchases only)
4. Send new invite to the *new* Apple ID's email
5. Accept on iPhone → Install
Enter fullscreen mode Exit fullscreen mode

100% works because it bypasses the lock entirely. But cumbersome for the tester (new Apple ID = new App Store purchase history etc).

Plan E: File Apple Engineering Feedback 

1. https://feedbackassistant.apple.com (sign in with dev Apple ID)
2. New Feedback → TestFlight → Bug Report
3. Subject: "TestFlight install fails with 'App not available' — tester record lock"
4. Description: timeline + ASC bundle ID + tester email + reference forum 702988
5. Submit → Receipt FB-XXXXXXXX
Enter fullscreen mode Exit fullscreen mode

Wait 3-7 days. Apple Engineering may reset the lock manually for your specific tester email. No guarantee but no cost either.

ASC API: hard-delete tester records script

For when the standard "Remove from Group" doesn't release the lock, you need account-level delete:

# orchestrator/scripts/asc_hard_delete_testers.py

import requests
import jwt
import time
from datetime import datetime, timedelta

KEY_ID = os.environ["ASC_KEY_ID"]
ISSUER_ID = os.environ["ASC_ISSUER_ID"]
KEY_FILE = os.environ["ASC_KEY_FILE"]
TARGET_EMAIL = "sh1990914@hotmail.com"

def gen_token():
    with open(KEY_FILE, "rb") as f:
        key = f.read()
    payload = {
        "iss": ISSUER_ID,
        "exp": int((datetime.now() + timedelta(minutes=10)).timestamp()),
        "aud": "appstoreconnect-v1",
    }
    headers = {"kid": KEY_ID, "alg": "ES256"}
    return jwt.encode(payload, key, algorithm="ES256", headers=headers)

token = gen_token()
hdr = {"Authorization": f"Bearer {token}"}

# 1. List all tester records (account level, all apps)
r = requests.get(
    "https://api.appstoreconnect.apple.com/v1/betaTesters",
    headers=hdr,
    params={"limit": 200, "filter[email]": TARGET_EMAIL}
)
records = r.json()["data"]
print(f"Found {len(records)} tester records for {TARGET_EMAIL}")

# 2. Hard-delete each
for rec in records:
    rid = rec["id"]
    r = requests.delete(
        f"https://api.appstoreconnect.apple.com/v1/betaTesters/{rid}",
        headers=hdr
    )
    print(f"Deleted {rid}: {r.status_code}")

print("Hard delete complete. Wait 10 min then re-invite.")
Enter fullscreen mode Exit fullscreen mode

Standard /v1/betaGroups/{group_id}/relationships/betaTesters DELETE only removes from a group. The above /v1/betaTesters/{id} DELETE removes the record entirely.

After running, wait 10 minutes for ASC propagation, then re-invite.

Note: If the Apple ID lock is still held on the backend, even hard-delete + re-invite won't unlock. You need Plan B/C/D/E.

What this taught me about Apple's TF infrastructure

Apple is the worst-documented backend in the indie dev tool stack. ASC API has 60+ endpoints, 8 of which I now understand only because I hit edge cases. Forum search is mandatory for anything past basic.

Lessons:

  1. Tester records ≠ group membership. Removing from group doesn't delete the record.
  2. Apple ID linkage is permanent for 90 days, not "deletable on delete."
  3. "App not available" error message is intentionally vague — Apple doesn't want to leak backend state details (security).
  4. Forum threads are gold. Apple staff occasionally drop authoritative answers (702988, 738484, 726078).
  5. TF install fail does NOT block App Store review submission. You can still ship to public users while TF is broken.

What I do now

For new TF testers:

  • Always use a fresh Apple ID for sandbox testing (not real personal)
  • Document tester email + Apple ID linkage in a CSV (lib/tester_log.py for me)
  • If a sandbox tester needs to be replaced, don't swap emails — create a new sandbox Apple ID

For my own personal tester (real iPhone for production smoke test):

  • Lock in 1 Apple ID per app forever
  • Don't switch sandbox accounts mid-development

For the original "stuck" sh1990914 lock:

  • Filed Apple Engineering Feedback (Plan E) — no reply yet (5/6/2026, day 8)
  • Tried Plan B (region switch) — partial success (1 of 4 apps installs)
  • Now waiting for July 28, 2026 (90-day natural unlock)
  • In parallel, pushing App Store review for production launch (TF doesn't block)

Reference

If you want the full debugging toolkit

I packaged 60+ ASC API Python scripts (tester management / build state / agreement check / IAP create / metadata edit / territory add / etc) as a Gumroad SKU. Includes:

  • asc_diag.py — 8-class TF install fail diagnostic
  • asc_hard_delete_testers.py — account-level tester delete
  • asc_reinvite_clean.py — DELETE+POST + reinvite cycle
  • asc_paid_agreement_check.py — verify agreement state
  • asc_create_iap.py — automate IAP creation
  • 55 more

Get them on Gumroad: $499 lifetime (placeholder link)

Or hire me for a 1 hr Tier 1 audit ($299): I look at your specific ASC + binary + reproduce the issue, give you a fix path. book.jiejuefuyou.consulting (placeholder)

Tags

#ios #appstoreconnect #testflight #indie #debug #swift

See also

A/B subject candidates

  1. "TestFlight install fail: the Apple ID lock nobody told you about"
  2. "I debugged TestFlight 'App not available' for 30 days. Here's what Apple Engineering told me."
  3. "TestFlight tester record lock: forum thread 702988 explained"

Top comments (0)