Troubleshooting File Loading Problems in Swift Apps

A problem that people learning to develop iOS and Mac apps run into is being unable to load files they include in their app, such as image files, sound files, and text files. This is a frustrating problem because your code is usually not the source of the problem. The problem is the operating system cannot find the file in the app bundle.

This article has tips on fixing file loading problems in your app.

Where do Swift GUI apps look for files?

Swift apps look for files in the Resources folder of your app bundle. When you write code to load a file, such as the following:

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

The operating system looks in the Resources folder. If it does not find the file, the function returns nil. The operating system does not search the entire app bundle, just the Resources folder.

It is very important that the files your app loads are in the app bundle’s Resources folder. If the files are not in the Resources folder, your app will not be able to load them.

Make sure the files are in the app bundle’s Resources folder

If you run into problems with loading files, make sure the files you want to load are going to be copied to the app bundle’s Resources folder when Xcode builds your project. To make sure the files will be copied to the Resources folder, make sure they are in the app target’s Copy Bundle Resources build phase. The files must be part of this build phase to get copied to the app bundle.

Take the following steps to see the files in the Copy Bundle Resources build phase:

1. Open the project editor by selecting the project file from the left side of the project window.
2. Select the app target from the target list on the left side of the project editor.
3. Click the Build Phase button at the top of the project editor.
4. Click the disclosure triangle next to the Copy Bundle Resources build phase.

If your files are not in the Copy Bundle Resources build phase, click the Add button below the list of files to open a sheet where you can choose the files to add to the build phase.

Make sure the file names match exactly

The code example earlier in this article,

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

Looks for a file with the name SampleData.json in the Resources folder. The Bundle class file search is case sensitive. If the name of the file in the app bundle is sampledata.json, the code example above won’t find the file because the file names don’t match exactly.

Also make sure you didn’t misspell the name of the file in your code. It’s easy to make a small typo that causes file loading problems.

Don’t include the dot when giving the file extension

The Bundle class’s url function takes a file extension as an argument. An easy mistake to make is to include the dot in the extension, such as the following code:

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: ".json")

With this code, the operating system is going to look for a file named SampleData..json, which most likely does not exist.

Do not include the dot when specifying file extensions.

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

Using folders of files in your app

If you include a lot of files in your app, you may place them in separate folders to make them easier to organize. You might have a folder for data files and a folder for audio files.

Suppose you have a separate folder for your JSON files. If you use the code I have used throughout this article to load a JSON file,

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

The url function returns nil because the JSON files are in a folder inside the Resources folder. The function looks in the Resources folder, doesn’t find the JSON file in that folder, and returns nil.

The fix is to add a subdirectory argument to the url function call and specify the name of the folder where the file is located.

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json", subdirectory: "JSON")