App Build Not Showing in TestFlight After Upload: How to Fix Build Number Conflicts

Table of Contents#

1. Understanding Build Numbers vs. Version Numbers
2. Common Causes of Build Number Conflicts
3. Step-by-Step Guide to Fix Build Number Conflicts
4. Advanced Troubleshooting
5. Preventive Measures to Avoid Future Conflicts
6. Conclusion
7. References

1. Understanding Build Numbers vs. Version Numbers#

Before diving into fixes, let’s clarify two critical terms: version number and build number. Apple uses these to track app updates, and confusing them is a common source of TestFlight issues.

Version Number (CFBundleShortVersionString)#

The version number is a human-readable string that communicates your app’s release stage to users and stakeholders (e.g., 1.0.0, 2.1.3-beta). It follows semantic versioning conventions (major.minor.patch) and is visible to users in the App Store.

• Purpose: Signals significant updates (major), new features (minor), or bug fixes (patch).
• Requirement: Must be incremented for public App Store releases, but TestFlight allows reuse only if paired with a new build number.

Build Number (CFBundleVersion)#

The build number is a numeric (or alphanumeric) identifier that uniquely identifies a specific build of your app (e.g., 42, 202405201234). It is not visible to end-users but is critical for Apple’s systems to track builds.

• Key Rule: For TestFlight, each build of the same version number must have a unique build number. If you upload a build with a build number that already exists for the same version, Apple will either reject it or silently fail to list it in TestFlight.
• Example: If your app’s version is 1.0.0 and you previously uploaded build 123, uploading another 1.0.0 build with 123 again will cause a conflict.

Why This Matters#

Apple’s systems use build numbers to differentiate between builds. A conflict means TestFlight cannot register the new build, leaving it “invisible” to testers. This is often the root cause of builds not appearing after upload.

2. Common Causes of Build Number Conflicts#

Build number conflicts don’t happen randomly. Here are the most frequent triggers:

Reusing Build Numbers for the Same Version#

The #1 cause: Uploading a new build with the same CFBundleVersion as a previous build for the same version number. For example:

• Version 1.0.0, Build 5 → uploaded successfully.
• Later, you fix a bug, re-archive, and upload Version 1.0.0, Build 5 again.
• Apple rejects the duplicate build, and it won’t appear in TestFlight.

Incorrect Increment Logic#

Teams often use manual or semi-automated build numbering (e.g., dates like 20240520). If two builds are uploaded on the same day with the same date-based build number, conflicts occur.

Xcode Auto-Increment Misconfiguration#

Xcode has an “Automatically manage signing” feature, but it does not auto-increment build numbers by default. If you assume Xcode handles this, you may accidentally reuse build numbers.

Target-Specific Build Number Conflicts#

If your app has extensions (e.g., iMessage, Today widgets) or companion apps (e.g., watchOS), their build numbers must also be unique and in sync with the main app. A conflict in a secondary target can block the entire build from TestFlight.

CI/CD Pipeline Errors#

Automated pipelines (e.g., GitHub Actions, Jenkins) may fail to increment build numbers due to misconfigured scripts, leading to duplicate uploads.

Delayed Processing in App Store Connect#

Rarely, builds take time to process (10–30 minutes). If you check TestFlight immediately after upload, it may not have appeared yet. Wait at least 30 minutes before troubleshooting—but if it’s been hours, it’s likely a conflict.

3. Step-by-Step Guide to Fix Build Number Conflicts#

If your build isn’t showing in TestFlight, follow these steps to resolve build number issues:

Step 1: Verify the Uploaded Build in App Store Connect#

First, confirm Apple received your build.

1. Go to App Store Connect.
2. Select your app → TestFlight → Builds.
3. Check the “Processing” or “Recent Builds” section. If your build isn’t listed here, it was either rejected or failed to upload.

Step 2: Check for Build Number Conflicts#

If the build isn’t in App Store Connect, check for duplicate build numbers:

1. In App Store Connect, go to Activity → All Builds.
2. Filter by your app’s current version (e.g., 1.0.0).
3. Look for existing builds with the same CFBundleVersion as your uploaded build. If a duplicate exists, this is the conflict.

Step 3: Update the Build Number in Xcode#

To fix the conflict, increment the build number to a value higher than any previous build for the same version.

Option A: Update Manually in Xcode#

1. Open your Xcode project.
2. Select your app target → General tab → Identity section.
3. Locate Build (this is CFBundleVersion).
4. Increment the number (e.g., from 123 to 124).
   • Pro Tip: Use a convention like [version].[build] (e.g., 1.0.0.124) for clarity.

Option B: Update via Info.plist#

If you prefer editing the raw plist file:

1. In Xcode, navigate to YourApp/Info.plist.
2. Find the key CFBundleVersion (or “Bundle version”).
3. Update its value to a unique number (e.g., 124).

Option C: Update for Multiple Targets#

If your app has extensions (e.g., widgets) or companion apps:

1. Repeat Steps 3A/3B for all targets (e.g., YourApp WatchKit Extension).
2. Ensure all targets use the same build number (Apple recommends consistency across targets).

Step 4: Re-Archive and Re-Upload the Build#

1. Clean your project: Go to Product → Clean Build Folder (or Shift+Cmd+K).
2. Archive the app: Product → Archive (or Cmd+Shift+I).
3. In the Archives window, select the new archive → Distribute to TestFlight.
4. Follow the prompts to sign and upload the build.

Step 5: Verify the Build in TestFlight#

1. Wait 10–30 minutes for Apple to process the build.
2. In App Store Connect, check TestFlight → Builds. The new build should appear with the updated build number.
3. If it still doesn’t show, check the upload logs (see Step 6).

Step 6: Troubleshoot Upload Errors#

If the build fails to upload or still doesn’t appear:

• Check Upload Logs: In Xcode, go to Window → Organizer → Select your archive → Show in Finder. Right-click the archive → Show Package Contents → Logs/Distribution.log. Look for errors like The build number already exists.
• Clear Derived Data: Go to Xcode → Settings → Locations → Click the arrow next to “Derived Data” → Delete the folder for your project.
• Restart Xcode: Sometimes, Xcode caches old build number data. Quit and reopen Xcode before archiving again.

4. Advanced Troubleshooting#

If the above steps don’t resolve the issue, try these advanced fixes:

Check for Cross-Platform Conflicts#

If you’re building for multiple platforms (e.g., iOS and macOS), ensure build numbers are unique per platform. For example, an iOS build 123 and macOS build 123 for the same version are allowed, but two iOS builds with 123 are not.

Use the App Store Connect API#

For programmatic visibility, use Apple’s App Store Connect API to check build status:

# Example: Fetch build details (requires API key)  
curl "https://api.appstoreconnect.apple.com/v1/builds" \  
  -H "Authorization: Bearer [YOUR_JWT_TOKEN]"  

Look for state (e.g., PROCESSING, VALID, INVALID) to confirm if the build was rejected due to a conflict.

Contact Apple Developer Support#

If all else fails, submit a ticket via Apple Developer Support. Include:

• App Store Connect app ID.
• Version and build number of the problematic upload.
• Screenshots of the upload logs (from Step 6).

5. Preventive Measures to Avoid Future Conflicts#

The best way to fix build number conflicts is to prevent them. Use these strategies:

Adopt Semantic Versioning#

Follow semantic versioning for CFBundleShortVersionString (e.g., MAJOR.MINOR.PATCH). For build numbers (CFBundleVersion), use an incrementing integer (e.g., 1, 2, 3) or a timestamp (e.g., 202405201234 for May 20, 2024, 12:34 PM).

Automate Build Number Increment#

Use CI/CD tools to auto-increment build numbers, eliminating manual errors:

Fastlane#

Fastlane’s increment_build_number action updates the build number automatically:

# Fastfile  
lane :beta do  
  increment_build_number(xcodeproj: "YourApp.xcodeproj")  
  build_app(scheme: "YourApp")  
  upload_to_testflight  
end  

GitHub Actions#

Add a step to increment the build number in your workflow:

# .github/workflows/testflight.yml  
- name: Increment Build Number  
  run: /usr/libexec/PlistBuddy -c "Set :CFBundleVersion ${{ github.run_number }}" YourApp/Info.plist  

Document Build Number Conventions#

Define clear rules for your team (e.g., “Build numbers for 1.0.x versions start at 100 and increment by 1”). Store this in your repo’s CONTRIBUTING.md or wiki.

Clean Up Old TestFlight Builds#

In App Store Connect, delete outdated TestFlight builds (TestFlight → Select build → Delete). This reduces clutter and makes it easier to track active build numbers.

Communicate with Your Team#

If multiple developers upload builds, use tools like Slack or Jira to announce new build numbers. Avoid overlapping uploads for the same version.

6. Conclusion#

A missing TestFlight build is often a sign of a build number conflict—a fixable issue with the right steps. By understanding Apple’s requirement for unique build numbers, updating conflicting values, and automating increments, you can ensure seamless TestFlight deliveries.

Remember: Prevention is key. Adopt semantic versioning, automate build number management, and communicate with your team to avoid future conflicts. With these practices, you’ll spend less time troubleshooting and more time shipping great apps.

7. References#

• Apple Developer Documentation: CFBundleVersion
• App Store Connect Help: Upload a Build to TestFlight
• Fastlane: Increment Build Number
• Semantic Versioning 2.0.0
• Xcode Help: Archive Your App