How do you find typos (syntax errors) in an improperly formatted plist
(property list) file, especially when Xcode provides absolutely no detail about badly formed XML? I often see plist
files with a thousand or more lines of text! In this article, I’ll show you how to fix plist
bugs — and do a few other things — by using the little-known plutil
command line tool.
How many times have you seen the following error message, shown below in textual and graphical format, when doing a build?
1 |
: couldn't parse contents of '/path/to/project/projectName/projectName/Info.plist': The data couldn't be read because it isn't in the correct format. |
Jump straight to the fix or take a minute to read a little background.
Background
When performing complex development with Xcode, it’s hard to avoid working with the plist
file. When creating a new project, Xcode automatically creates one named “Info.plist” and makes it part of your physical folder structure and includes it very obviously in the Project Navigator
. You can rename it to your own liking, and sometimes use multiple plist files, especially when you have multiple targets. While some people recommend only editing the contents of OS X or iOS project plist
files using the Xcode user interface, I find that advice to be unrealistic.
One common scenario for custom usage of the plist
file comes to mind:
- What if your app supports its own file format and your files have a unique extension?
- Say that your users want those files to automagically open in your app when they select one in the iOS
Files
app or macOS’sFinder
? - Say your users exchange your proprietary files using text messages or email.
When someone receives one of those files and wants to open it with your app, you’ll have to… Guess what? Add and configure the Document Types
, Imported UTIs
, and Exported UTIs
sections of your app project’s plist
file. Doing so is beyond the scope of this article, but I mention it to emphasize the importance of plist
files. If you want to learn about associating files with your apps, I suggest you start by reading Apple’s “Technical Q&A QA1587 – Q: How do I get my application to show up in the “Open in…” menu on iOS for a specific document type?”
I was once working on an app that supported over 40 file type associations, all with different file extensions (i.e., filename.ext where ext is the extension). Once I created my first Document Types
and Exported UTIs
elements, I opened my plist in Source Code
view and used copy and paste to configure the remaining 40+. To make sure my XML was formatted properly, I switched from Source Code
view back to Property List
view. Guess what happened when Xcode parsed my XML so it could show my plist as a Property List
? Bang — useless error message. Watch:
All’s I get is a dialog box that says “The data couldn’t be read because it isn’t in the correct format.” I get the same message when building. So with Xcode, I have to go through possibly a thousand lines of code to find the error?
The fix: plutil
Before you start reading through a thousand lines of XML to find some minor syntax errors that are giving you major headaches, try the plutil
command line utility, or as the OS X man
page calls it, the “property list utility.” Open Terminal
, change directory (cd
) to the folder that contains the offending plist
file, and enter the following command:
1 |
% plutil Info.plist |
Of course, enter the name of your plist
. You’ll get some very helpful output. It will help you fix your error(s). Here’s what plutil
told me was the problem with my plist:
1 2 3 |
% plutil Info.plist Info.plist: Encountered unexpected character / on line 37 while looking for open tag |
Let’s look at line 37 of my plist
and see exactly what’s wrong, in textual and graphical format:
33 34 35 36 37 38 |
... <true/> <key>NSSupportsSuddenTermination</key> <true/> /dict> </plist> |
This could be an instance of where I copied and pasted, but missed a single character when copying, or I was typing XML and forgot the open bracket (“<") for a tag. Pretty simple, right?
Where to go next
I urge you to take a look at the documentation on plutil
by bringing up its man
page at Terminal's
command prompt:
1 |
% man plist |
There are quite a few interesting things you can do with plutil
. You can print the contents of your plist
in a very readable json
format. I find this option very useful when troubleshooting. If you type plutil -help
, you can get very detailed assistance in using this utility for converting your plist
into binary, setting or replacing individual values, inserting new values, and printing individual elements. This is deep down in the weeds but, trust me, when troubleshooting some apps, like the one I discussed above with file associations, you’ll be glad you learned about plutil
.