Which iOS app version/build number(s) MUST be incremented upon App Store release?

Question

Version/build fields for an iOS app include:

• "Version" CFBundleShortVersionString (String - iOS, OS X) specifies the release versi

Answer 1

AFAIK, off the top of my head, you only need to increment the build number CFBundleVersion. Incrementing the short version string is not necessarily needed, though you probably should increment it, as it does tell the user that the app is new. Apple does say that numbering should follow traditional software versioning conventions, however, and iTunes Connect may complain if you try to re-upload an already existing version.

Long story short, it may work, but probably not.

Answer 2

You need to increment both.

When uploading a new version, you will need to create a new version on the iTunes Connect, which automatically will be higher than the previous releases. This version on the iTunes Connect will be expecting a binary with the same version number, thus CFBundleShortVersionString needs to be incremented.

If you update the version but forget to increment the CFBundleVersion, you will encounter an error during the upload. See pkamb's answer and screenshot.

For details on CFBundleShortVersionString and CFBundleVersion, please see: https://stackoverflow.com/a/31921249/936957

Answer 3

I'm preparing to release a new Mac App Store app. Using CalVer formatting of YEAR.release (build).

I uploaded several builds: 2020.0 (1), 2020.0 (2), etc. I finally submitted 2020.0 (8) for App Store Review. That passed review and is in the state Pending Developer Release.

I wanted to fix a few things before release, so I added a new build to the same release train: 2020.0 (9).

That results in the error:

App Store Connect Operation Error

ERROR ITMS-90062: "This bundle is invalid. The value for key CFBundleShortVersionString [2020.0] in the Info.plist file must contain a higher version than that of the previously approved version [2020.0]. Please find more information about CFBundleShortVersionString at https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleshortversionstring"

which is annoying as my 2020.0 version was never actually released. From the accepted answer of this question I was under the impression that until the app was available on the App Store you could continue to release new builds with the same version.

• Error ITMS-90062: The value for key CFBundleShortVersionString must contain a higher version than that of the previously approved version
• Application Loader ERROR ITMS-90062: The value for key CFBundleShortVersionString must contain a higher version

The solution seems to be that a "release train" (Same Version + New Build) cannot be updated if the app state is Pending Developer Release. Either release your existing build and then increase the version, or Cancel this Release in App Store Connect to allow further uploads for this release train.

Answer 4

Apple Technical Note TN2420, Version Numbers and Build Numbers

Summary:

• The pair (Version, Build number) must be unique.
  • The sequence is valid: (1.0.1, 12) -> (1.0.1, 13) -> (1.0.2, 13) -> (1.0.2, 14) ...
• Version (CFBundleShortVersionString) must be in ascending sequential order.
• Build number (CFBundleVersion) must be in ascending sequential order.

---

Version Number and Build Number Checklist

Here are some things you can check when submitting a new build to the App Store. Making sure you have your Version Number and Build Number set properly will help you by avoiding having your App automatically rejected for having them improperly configured.

1. For each new version of your App, you need to invent a new Version Number. This number should be a greater value than the last Version Number that you used. Though you may provide many builds for any particular release of your App, you only need to use one new Version Number for each new release of your App.
2. You cannot re-use Version Numbers.
3. For every new build you submit, you will need to invent a new Build Number whose value is greater than the last Build Number you used (for that same version).
4. You can re-use Build Numbers in different release trains, but you cannot re-use Build Numbers within the same release train. For macOS apps, you cannot re-use build numbers in any release train.

---

Based on the checklist, the following (Version, Build Number) sequence is valid too.

• Case: reuse Build Number in different release trains. (NOTE: NOT macOS app)

  (1.0.0, 1) -> (1.0.0, 2) -> ... -> (1.0.0, 11) -> (1.0.1, 1) -> (1.0.1, 2)

Answer 5

I can confirm, having just tried it both ways, that a sequence of version and build numbers like...

1.0.0 (1)
1.0.1 (1)
1.0.2 (1)

...will be accepted for iOS apps, but for Mac (Catalyst) apps it returns this error:

ERROR ITMS-90061: "This bundle is invalid. The value for key CFBundleVersion [1] in the Info.plist file must contain a higher version than that of the previously uploaded version [2]."

The Mac version and build numbers would need to go like...

1.0.0 (1)
1.0.1 (2)
1.0.2 (3)

For iOS, I used to enter build numbers as the version number plus a fourth digit, like...

1.0.0 (1.0.0.1)
1.0.1 (1.0.1.1)
1.0.2 (1.0.2.1)

...but that isn't allowed for Mac apps, either. When I tried submitting my first Mac (Catalyst) app, Apple would only accept a build number with three or fewer digits:

ERROR ITMS-9000: "This bundle is invalid. The value for key CFBundleVersion [1.0.0.1] in the Info.plist file must be a period separated list of at most three non-negative integers."

So I changed to a single number that increments for every build and continues incrementing across version numbers.

Answer 6

The current Apple Technical Note TN2420, Version Numbers and Build Numbers says (my bolding):

4. For iOS apps you can re-use build numbers in different release trains, but you cannot re-use build numbers within the same release train. For macOS apps, you cannot re-use build numbers in any release train.

Unfortunately, this means you can't reuse a build number that tracks to the release train number on iOS when you're trying to release the same build on Mac Catalyst.

In my case, for example, due to some earlier issues, I ended up releasing 1.0.2(4) as a Mac Catalyst app that corresponded to 1.0.2(1) on iOS. Now when trying to release 1.0.3(1) on both, the app fails verification on MacOS because of the build number, while it passes verification on iOS.

I guess now that I am releasing the same app on both iOS and MacOS routinely, I will adopt build numbers that correspond to the date, like 20200111 and increment with a decimal point if I need to change the build number within a given release.