App Store Rejection: The Xcode Configuration Issues Apple Won't Debug for You

The review delay problem

Apple's standard review turnaround is 24–48 hours. A single rejected submission costs you that window plus the time to diagnose and fix the issue. Two rejections costs a week. Three is a common pattern for configuration-related issues because the rejection message often identifies the symptom rather than the root cause.

Configuration issues are almost entirely preventable with a pre-submission checklist. The failure modes below account for the majority of configuration-triggered rejections seen in production.

1. Signing certificate mismatches

The most common source of binary validation failures: a development certificate in a target that should be using a distribution certificate, or a certificate that is present in Keychain but is expired or revoked.

• —Every target in the scheme — app, Watch app, Widget extension, Share extension — must be signed with the same team's distribution certificate for App Store submission. Verify each target individually, not just the main app target.
• —Automatic signing in Xcode resolves this correctly most of the time. It fails silently when a target has manual signing overrides from a previous developer or CI configuration. Check every target's “Signing & Capabilities” tab individually.
• —Run codesign -dv --verbose=4 <path-to-app> on the archive before uploading to verify exactly which certificate signed each binary.

2. Entitlement file gaps

The pattern: you enable a capability in the Apple Developer Portal (HealthKit, CloudKit, Push Notifications, iCloud Documents), the capability shows in App Store Connect, but the corresponding entitlement key is missing from the target's .entitlements file.

When Xcode adds a capability via the “+ Capability” button, it updates the entitlements file automatically. When capabilities are added via the Developer Portal directly (often done during provisioning profile setup), the entitlements file is not updated automatically. These get out of sync silently and fail at submission.

• —Cross-reference the App ID's enabled services in the Developer Portal against the keys in every target's .entitlements file before every submission.
• —Watch app and extension targets need their own .entitlements files. The main app's entitlements are not inherited.
• —CloudKit containers: the container identifier in the entitlements file must exactly match the container you configured in the portal. A single character difference causes a silent rejection during binary validation.

3. Watch and Widget target linking issues

Extension targets (Watch App, Widget, Share Extension) are the most common source of linking failures in multi-target apps. The failures surface in different ways: build errors on device, archive validation failures, or TestFlight processing rejections.

• —Shared code must be in a Swift package or framework, not in the main app target. Including .swift files directly in multiple targets causes duplicate symbol errors on archive.
• —App Group identifiers must be configured on every target that shares data. An App Group added to the main target but missing from the Watch target causes WatchConnectivity to fail — and the mismatch only surfaces at runtime, not at build time.
• —Widget network extensions must declare their access level in the entitlements. Widgets that make network requests and are not declared as background URL session capable fail App Store review under the network use guidelines.

4. Bundle ID consistency failures

Extension Bundle IDs must use the parent app's Bundle ID as a prefix. A Widget extension for com.example.myapp must be com.example.myapp.widget — not com.example.widget.

This is a hierarchical constraint enforced during App Store processing. It is not validated during development builds. The failure only surfaces at submission or TestFlight processing time, making it a particularly expensive mistake to catch late.

Automate the pre-submission check

Xcode Doctor automates exactly this checklist — scanning your project for signing mismatches, entitlement gaps, Bundle ID hierarchy violations, and target configuration issues before you archive. It surfaces the problem with a specific fix, not a generic error message.

It is the tool we built after seeing the same pattern repeatedly: an app that builds cleanly on device, passes the simulator, and fails App Store validation for a reason that takes hours to diagnose from the error log.