Technical Analysis: The iTunes Broken Promise: Broken Links

One of the reasons we are fans of Apple is that an implicit proposition of being a customer is that our computing life will be simpler, less vexing, and more productive. With iTunes, however, that promise is broken in part.

We know that iTunes is a money machine for Apple. Accordingly, development resources are going to be applied first to the maintenance and improvement of its ability to secure the revenue stream. Unfortunately, when it comes to the hard work of making iTunes a blissful and reliable application, efforts have been lacking. The area of focus here is the iTunes broken link.

iTunes glamor shot


It's not the cause of the issue, but a broken link is related to the fact that iTunes keeps a database, in XML format, of your iTunes library. (Actually, it also creates a binary version for faster access, but will revert to the .xml file if necessary.) It contains all kinds of useful metadata, such as song rating, lyrics, cover art and play count -- plus a pointer to the actual song. You'll see this file in your iTunes directory: "iTunes Music Library.xml."

Separate from the database itself is the actual library of songs. That's in a directory called iTunes Music, and that directory can be moved -- so long as you tell iTunes where you put it. Say, an external drive. You do this in iTunes -> Preferences -> Advanced -> iTunes Media Folder Location. See the link above for other housekeeping details.

This schema, in principle, should work fine, but the opportunities for both unexpected user actions, difficult Time Machine file recoveries, and lack of iTunes software robustness can lead to a situation where the iTunes database no longer knows where the actual song is -- even though it's easy enough for the user to find it with a simple Finder search. The broken link is indicated with an exclamation mark, like this:

iTunes broken links

Broken Links

Apple's first line of defense against this is an almost DOS-like, pathetic avoiding of responsibility by iTunes engineers. When you double click a song that has a broken link, iTunes invites you to go look for it, manually, with a File dialog box. That's not the user experience Apple is famous for.

iTunes Find song

The cop-out leads to File dialog...

If you have a few of these, they're easy to fix. If you have a hundred or more, the process can become tedious. Right away, you'll find yourself looking for an iTunes menu item that can do the tedious work for you. In principle it would look like this:

File-> Fix Broken Links
   -? Please specify the the location of the iTunes Library
      -Code -> Finds all the songs w/ broken links and mends the link.
      -? Asks for confirmation if in doubt.


If there's any doubt, the function can throw up both the metadata and the path information to confirm the association. Such a function is missing in iTunes and remains an arrogant testament to the notion that Nothing Can Go Wrong. (Or Apple engineers didn't have the time to write the code. Or the product manager doesn't want to admit that there's a problem that requires attention.)

The next thing the user may do is search around on the Internet for a utility that does this dirty job for them. Alas, neither Jeff Gamet nor I have been able to find one that specifically addresses this limited problem. A search will come up with TuneUp from and an AppleScript written by Jennifer Croft. While encouraging at first, it doesn't appear that either of these solutions addresses the specific task described in the hypothetical menu function above. Instead, they drag the user into a blind alley of false hope, other functions, then frustration.

The third option is to manually fix the broken links as they arise or all at once if one has the patience. I did this by having a Finder search window under iTunes, searching for the song name, then using the path info at the bottom of the search window to guide me to the song when iTunes asks for the song location. In the screen shot below, I've overlapped the two windows to make the image bigger and easier to read.

iTunes + search

iTunes & Search windows overlay

iTunes search magnified

Magnified view of above

One of the impediments to an easy solution is that, to fix the link, one has to carefully edit the .xml database file. One can do that with a command line editor, like pico, nano, vi, etc. But requires a bit of knowledge about the structure of the XML and is a technical hurdle that would keep most users from easily writing their own utility. Also, the technology of iTunes changes rapidly over time. Accordingly, the heavy lifting here should be done by Apple, not the user.

A search of the Apple and MacOSHints user forums hasn't revealed any insanely simple solutions. However, there's no guarantee that I haven't overlooked something, and reader feedback is welcome.

There are many complexities and opportunities for problems with the schema Apple has chosen. For some users, the only sane solution is to blow out the iTunes support files and start all over with iTunes -> File -> Add to Library. This will rebuild everything, but will also reset all the metadata you've built up, such as play count, rating and lyrics. For those who don't care about that, it's another painful but workable course of action.

iPhone Sync

Another way in which the user can become frustrated by broken links is when syncing playlists to an iPhone or iPod touch. When there are broken links in a playlist to be synced, iTunes will throw up a dialog box like this:

iTunes sync error

iTunes sync warning

The issue here is that there's absolutely no way to print, select, or copy this list -- which can be long. The best the user can do is scroll through the list. Those who would like to attend to broken links, first, for their iPhone will not be able to use that dialog box as a helpful basis. Instead, one must identify all playlists to be synced, then clean up those playlists, and finally re-sync the iPhone.


iTunes is a fabulous product, but somehow, along the way, Apple has seemingly failed to roll into the product a first class schema for robustness, error correction, and a user-friendly menu item to do the work only a computer should be doing. Instead, in a cop-out, iTunes asks the user to do all the grunt work of finding and selecting songs when the link is broken. To fulfill Apple's implicit promise to make our life better, something more capable than that is called for.

As I said above, reader feedback is most welcome here, especially in the area of automated tools to fix an abundance of broken links or better workaround procedures. If our community comes up with an elegant solution, I'll post a follow-up article.