Xcode Cloud Troubleshooting

Last Updated: 2026-01-24 Status: Active reference for Xcode Cloud issues

---

Overview

This guide documents common issues encountered when building the Archery Apprentice iOS app on Xcode Cloud, along with their solutions.

---

KSP Plugin Not Found

Added: 2026-01-24 PR: #480

Symptoms

Build fails on Xcode Cloud with error:

Plugin [id: 'com.google.devtools.ksp', version: '2.x.x-x.x.x'] was not found in any of the following sources

The same build succeeds locally and on GitHub Actions.

Root Cause

Xcode Cloud’s Gradle plugin resolution differs from standard builds. The KSP (Kotlin Symbol Processing) plugin requires explicit module mapping to resolve correctly.

Solution

Add a resolution strategy to settings.gradle.kts:

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    // Explicit resolution strategy for KSP plugin (fixes Xcode Cloud resolution issues)
    resolutionStrategy {
        eachPlugin {
            if (requested.id.id == "com.google.devtools.ksp") {
                useModule("com.google.devtools.ksp:symbol-processing-gradle-plugin:${requested.version}")
            }
        }
    }
}

Why This Works

The resolutionStrategy block tells Gradle exactly which module to use for the KSP plugin ID. Without this, Xcode Cloud’s environment may fail to resolve the plugin through standard lookup mechanisms.

Verification

After applying this fix:

1. Verify local build still works: ./gradlew :shared:compileKotlinIosArm64
2. Push to trigger Xcode Cloud build
3. Verify build succeeds in Xcode Cloud dashboard

---

App Store Version Train Issues

Added: 2026-01-24 PR: #478

Symptoms

App Store Connect rejects submission with:

The version train for this app is closed

Or

A version with this number already exists

Root Cause

App Store Connect version trains have strict rules:

1. Once a version is submitted for review, its version number is “claimed”
2. If that submission is rejected or withdrawn, the version number may still be locked
3. The next submission must use a higher version number

Solution

Bump the MARKETING_VERSION in Xcode project settings:

MARKETING_VERSION = 1.0.2;  // From 1.0.1

Where to update:

• iosApp/ArcheryApprentice.xcodeproj/project.pbxproj
• Update in BOTH Debug and Release build configurations

Version Numbering Strategy

Scenario	Action
App Store rejection (bug fix resubmission)	Bump patch: 1.0.1 → 1.0.2
New features	Bump minor: 1.0.x → 1.1.0
Major release	Bump major: 1.x.x → 2.0.0

Lessons Learned

1. Always bump version after rejection - Even if only fixing metadata
2. Check TestFlight builds - Old builds can block version numbers
3. Use build numbers for iteration - CURRENT_PROJECT_VERSION can increment without changing marketing version

---

Java Version Detection

Added: 2025-12-XX (from earlier PR #451)

Symptoms

Xcode Cloud build fails with:

Unsupported Java version

Or Gradle daemon crashes.

Solution

The ci_scripts/ci_post_clone.sh script handles Java 21 installation:

# Install Java 21 via Homebrew
brew install openjdk@21
 
# Set JAVA_HOME for Gradle
export JAVA_HOME=$(/usr/libexec/java_home -v 21 2>/dev/null || echo "/opt/homebrew/opt/openjdk@21")

Key Points:

1. Xcode Cloud uses macOS with Homebrew available
2. Java must be installed in ci_post_clone.sh (runs after repository checkout)
3. The script should handle both Intel and Apple Silicon paths

---

Framework Search Path Issues

Reference: KMP iOS Patterns

Symptoms

Build fails with:

Framework not found shared

Or linker errors mentioning KMP framework.

Solution

Ensure framework search paths include all build variants:

FRAMEWORK_SEARCH_PATHS = (
    "$(inherited)",
    "$(SRCROOT)/../shared/build/xcode-frameworks/$(CONFIGURATION)/$(SDK_NAME)",
);

The path must include:

• $(CONFIGURATION) - Debug/Release
• $(SDK_NAME) - iphoneos/iphonesimulator

---

Common Environment Differences

Aspect	Local/GitHub	Xcode Cloud
Java	Pre-installed JDK 21	Must install via ci_post_clone.sh
Gradle	Uses wrapper	Uses wrapper (same)
Plugin resolution	Standard	May require explicit resolution strategy
Signing	Manual/match	Automatic Cloud signing
Simulator	Available	Not available for UI tests

---

Debugging Tips

View Xcode Cloud Logs

1. Open Xcode
2. Go to Report Navigator (Cmd+9)
3. Select Cloud tab
4. Click on failed build
5. View detailed logs

Test ci_post_clone.sh Locally

# Simulate Xcode Cloud environment
export CI=true
export CI_XCODE_CLOUD=true
cd iosApp
./ci_scripts/ci_post_clone.sh

Force Clean Build

If builds are inconsistent, try:

1. In Xcode Cloud settings, enable “Clean build folder”
2. Or delete derived data in Xcode Cloud (if option available)

---

Related Documentation

• KMP iOS Integration Patterns - Swift/Kotlin interop patterns
• iOS Troubleshooting Guide - General iOS issues
• Hybrid Runner System - GitHub Actions setup

---

Tags: ios xcode-cloud troubleshooting ci-cd Status: Active reference