Uploading an iOS App to the App Store
Got here via Google and have Xcode error 22421 or similar? Scroll down to our “Common Issues” section 👇
After months of working on your iOS app, you’re finally ready to put it on the App Store. You look up Apple’s docs and find the App Store Connect Developer Guide. And you discover dozens of documents without any obvious “do this to submit your app for review” checklist.
In this series of posts, we’ll fix that. We’ll help you wade through the docs and skip the screens that you don’t need. This is part 1, how to upload the actual app to the App Store. Later parts will take care of everything else happening in and around App Store Connect.
If you haven’t yet, you’ll need to create a developer account with Apple and sign up for the Developer Program. You can do that as a company or individual. You might have to send some paperwork to Apple so try to do it well before you need to submit your app.
Once you have a developer program account, make sure Xcode knows about it. Add the Apple ID for your account in Xcode under Preferences -> Accounts. Now Xcode can take care of most of the provisioning issues for you.
You’ll also get access to App Store Connect. Head over there, log in and choose the Agreements, Tax, and Banking section. Before publishing an app you’ll have to accept some of those agreements and set up your banking info so you can get paid. You’ll also need to set up tax info, depending on your country.
If you already have an App Store Connect account, make sure that your role is Admin, Technical, App Manager, or Developer. Only those roles can upload a build.
Create an App Record in App Store Connect
When your app is ready to upload, you can add the app to App Store Connect. (You should probably tag it in your version control first.)
In-App Store Connect go to the My Apps section and hit the plus sign on the left side to create a new app. You’ll get a little form to fill out with your app’s info:
Most of those fields should be self-explanatory. The Bundle ID is a unique identifier for your app. It should match what you’ve set in Xcode for the target’s Bundle Identifier. If you’ve set up In-App Purchases or Game Center (or any of a few other features), you should already have set up a Bundle ID in the Developer Portal. If you haven’t, you can either go to the dev portal to create one now or choose the wildcard and copy your bundle ID from Xcode. If you’re going to be adding IAPs or GameKit, you should probably just go add the Bundle ID to the portal now.
Hit Create andApp Store Connect will create a record for your app. Look on the left-hand side and select the 1.0 release under iOS App. Scroll down to the build section. This is where you’ll be able to see your uploaded app.
You’ll see a note that you can use Xcode or Application Loader. You probably already have everything set up in Xcode so we’ll assume you’re using that.
When would you use Application Loader? You can use Application Loader to submit your app for review if you’re getting a build from a developer (in ipa format) and don’t have Xcode installed. You’ll still need a Mac since that’s the only operating system Application Loader runs on.
You can use Application Loader to include In-App Purchase with the app too. If you want to try out Application Loader and don’t have Xcode installed, get it from Resources and Help section of App Store Connect. If you do have Xcode installed but don’t want to use it, you can access Application Loader under the Xcode -> Open Developer Tool menu.
Before you go any further, make sure your app is really, really ready for submission. You won’t be able to make any changes before launch (unless you upload another build and have Apple review it). Verify everything from your app’s display name to whether you’ve removed any in progress or testing code that might have been included.
Uploading the Build
Since we already set up the app in App Store Connect and Xcode knows about our dev account, it’ll know where to put it when we upload it.
Open your project in Xcode. Select Archive in the Product menu. Choose Save for iOS App Store Distribution. That’ll create the build to be submitted.
When it’s ready you’ll see an Archives window. You can get back to this screen by selecting Organizer in the Window menu. Make sure the archive you just created is selected and that the version number is right.
To upload your app, click on the big blue Upload to App Store button on the right side. You’ll have to confirm for Xcode that it’s going to upload the app to the right place. If you’re on multiple iOS dev teams, you’ll have to pick the one it should use. When Xcode has it all figured out, it’ll show you a summary screen. Click the Upload button.
While you’re waiting, grab a coffee or take a walk. It’ll take a little while. While you’re waiting for Xcode & Apple’s servers will be doing some verification (like making sure you’re not using private APIs), prepping of the archive, and finally uploading the build.
Assuming everything went fine, you should see a nice Upload Successful checkmark:
Your app is uploaded to App Store Connect. To check, close Xcode and go back to your app’s v1.0 record inApp Store Connect.
Under Builds, nothing has changed yet:
So click on Select a Build Before You Submit Your App. Then choose your recently uploaded build. (If it’s still showing as Processing, just wait a bit and it’ll become available.)
Now the Builds section should show your upload:
TestFlight Beta Testing
If instead of submitting your app to the App Store you want to run a beta test using TestFlight, the process is almost exactly the same.
Before archiving the build, you’ll need to create an App Store Distribution profile with the beta entitlement turned on. Make sure that distribution profile is selected in Xcode when you create the archive.
If you want to invite internal testers, you don’t need to fill out anything in App Store Connect. For external testers, you’ll need to specify an App Description and What to Test then submit the app for Beta Review.
There are a few common problems that you’ll probably run into at some point when pushing apps to the App Store.
Uploading in Xcode Doesn’t Work
If you see “Cannot verify client”, “Not authorized”, “This Action could not be completed”, or other errors not related to signing & provisioning profiles then you’ve got a problem with Xcode’s upload function. Usually, the problem is on the other end, wait and try again. Use the time productively: grab a cup of coffee, go for a walk, or do a few push-ups.
If you want to do something, here’s a list of things to try:
- Make sure you’re not using a beta version of Xcode.
- Disable any virus scanners
- Restart Xcode, clean, and rebuild
- Hit Validate first then try to upload again
- Use Xcode to generate an archive then using Application Loader to upload it. Choose “Save for iOS App Store Deployment” to get Xcode to generate the archive. In Application Loader, select “Deliver You App” and choose the ipa file that Xcode generated. ⚠️
Using Application Loader to upload the IPA seems to work for most people, where Xcode timed out before.
If you can’t create an archive in Xcode, usually it’s because you have the destination set to the simulator. Switch to iOS Device (it should work even if you don’t have one connected).
Another cause for the grayed out archive option is that it’s disabled for your scheme. Under the Product menu, choose Scheme then Edit Scheme… With Build selected on the left, make sure that the checkbox for Archive is enabled.
Signing & Provisioning Errors
Xcode takes care of most signing and provisioning now but issues still crop up. Eventually, you’ll have to fight with a provisioning or signing issue so it’s worth reading Apple Maintaining Your Signing Identities and Certificates docsso you know how it all works.
The error messages for these errors are often misleading. A quick trip to Apple’s Troubleshooting list is usually more productive than trying to reason out the issue based on the message.
If your error isn’t listed there then try Google. Sometimes errors crop up for everyone for a while, like when Apple’s WWDR intermediate certificate expired recently.
Sometimes after uploading a build, the status will change to “processing” and you won’t be able to select that build for your app version. Usually, this step only takes a few minutes at most. But once in a while, a build will seem to randomly get stuck at this stage. Even on my tests while writing this article I had one build upload that decided to take an hour to “process”. Usually, the best thing to do is wait it out, it should only take a few hours at most. If it takes more than 24 hours, contact App Store Connect support.
Before you can submit the app for review you’ll have to provide out a ton of data, including the app description, keywords, screenshots, … Entering all of that info can be a real time sink when you thought you were ready to submit your app. Next time we’ll talk about how to do all of that so you can get your app on the App Store.