Troubleshooting

iOS development has a specific set of failure modes that catch most people off guard. This doc covers the most common ones and how to fix them.

Provisioning profile issues

Symptoms: "No provisioning profiles with a valid signing certificate" or "Provisioning profile doesn't include the currently selected device."

• Fix 1: Xcode → Preferences → Accounts → select your team → Download Manual Profiles
• Fix 2: Delete derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
• Fix 3: In Xcode Signing & Capabilities, uncheck then re-check "Automatically manage signing"
• Fix 4: If on a new device, add the device UDID to your developer portal at developer.apple.com → Devices

Build errors after adding a package

Symptoms: "No such module" after adding a Swift Package Manager dependency.

• Clean build folder: Cmd+Shift+K
• Reset package caches: File → Packages → Reset Package Caches
• Close Xcode, reopen the project
• If still failing: delete DerivedData and rebuild

Claude Code writing outdated Swift patterns

Symptoms: Claude uses ObservableObject, NavigationView, @Published, or @StateObject in new code.

• Root cause: Missing or incomplete CLAUDE.md
• Fix: Add explicit instructions to your CLAUDE.md: "Never use ObservableObject, NavigationView, @Published, or @StateObject in new code."
• Fix 2: Install the AvdLee SwiftUI Expert Skill if you haven't (Doc 3)
• Fix 3: Tell Claude directly: "Refactor this to use @Observable and @MainActor as per our CLAUDE.md"

App Store rejection reasons

• 2.1 App Completeness: App crashes or has placeholder content. Fix: complete testing in Doc 10.
• 5.1.1 Privacy: Missing privacy description strings for permissions. Every NSLocationWhenInUseUsageDescription, NSCameraUsageDescription, etc. must have a clear user-facing explanation.
• 4.2 Minimum Functionality: App doesn't provide enough utility. Fix: ensure your app does something meaningful that couldn't be done in a webpage.
• 3.1.1 In-App Purchase: If you charge for features, it must go through Apple's IAP system. No PayPal, Stripe, or other payment links for digital goods.
• 1.0 Objectionable Content: User-generated content without moderation.

Simulator vs device discrepancies

• Push notifications: Don't work on Simulator for real APNs. Use physical device.
• Performance: Simulator uses your Mac CPU. An animation that's smooth on Simulator may lag on an iPhone SE. Always test on the lowest-spec device you support.
• Camera: Simulator camera returns a static image. Real camera only works on device.
• Face ID / Touch ID: Simulator can simulate biometrics via menu. Test real flows on device.

SwiftData migration issues

Symptoms: App crashes on launch with "SwiftData error: No model found" or schema migration crash.

• If you changed a @Model schema, you need a ModelMigrationPlan
• For development: delete and reinstall the app on Simulator to clear the store
• For production: write a migration plan before submitting the update

// Delete the SwiftData store on Simulator:
let container = ModelContainer(for: YourModel.self,
    configurations: ModelConfiguration(isStoredInMemoryOnly: true))

Xcode is using the wrong Swift version

# Check which Xcode is active:
xcode-select -p

# Switch if needed:
sudo xcode-select -s /Applications/Xcode.app