Xcode 16 Buildable Folders Break Xcode 15 Backwards Compatibility

Paul Solt

Aug 21, 2024 • 2 min read

The project cannot be opened because it is in a future Xcode project file format.

Did you make changes to your file structure in Xcode 16? If so you might not be able to open your Xcode project in Xcode 15 or earlier.

You may get an error in Xcode 15.4:

"The project at ... cannot be opened because it is in a future Xcode project file format. Adjust the project format using a compatible version of Xcode to allow it to be opened by this version of Xcode."

There is a new concept of "Buildable Folders" that behave differently in Xcode 16 and it is not backwards compatible if you are not aware. You need to stick to Group with or without Folders in Xcode 16.

Minimize project file changes, and avoid version control conflicts with buildable folder references.Convert an existing group to a buildable folder with the “Convert to Folder” context menu item in the Project Navigator. Buildable folders only record the folder path into the project file without enumerating the contained files. This minimizes diffs to the project when files are added and removed, and avoids source control conflicts with your team.To use a folder as an opaque copiable resource, the default behavior before Xcode 16, uncheck the “Build Folder Contents” option in the File Inspector. (123729918)

and

The Project Navigator now defaults to creating groups with associated folders when using the “New Group” and “New Group from Selection” commands. To create a group without a folder, hold option in the context menu to reveal the “New Group without Folder” variant of the command. (127396845)

When I created an Xcode project with Xcode 16 Beta 2 or Beta 4, the project was unable to be opened due to the buildable Folders that were created (maybe because I used Swift Testing).

Blue folder icon = Buildable Folder on Xcode 16
Gray folder icon = Group with folder
Gray folder icon (with bottom left triangle) = Group without folder

Solution

Right-click on the folder in Xcode 16 and "Convert to Group"

That should work recursively for all the files and folders in that Folder. Keep in mind you may need to play around with the file/folder structure to get it to work.

There is some internal magic happening under the hood.

If you have an incompatible file or folder (Group without folder), you may see an error message about "Missing Associated Folder."

It is still confusing to me, because on Xcode 15 you can add a folder, which gives the Blue icon, but that works in Xcode 15 and Xcode 16.

Links:

If you have any details, please comment down below or reach out on X: @PaulSolt.

Solution

Sign up for more like this.