Distinctive icons, for documents, apps, and more, has been one of the major features of every Mac operating system. Delivering those icons correctly has also been one of the long-standing problems which users have had to grapple with. Every version of Mac OS and macOS to date has, on occasion, got this wrong. This article explains, in as much detail as I know, how macOS Mojave works this little bit of magic, and how to tackle it when that magic stops.

Back in the days of Classic Mac OS, document and other icons were stored in what was known collectively as the Desktop Database. Every file had four-character creator and type codes, and what the Finder did was look up the correct icon to display to match the creator and type. This may seem so simple as to be infallible, but every so often the Desktop Database would get corrupted, and documents and apps started appearing with generic rather than custom icons. The answer then was to force the Desktop Database to be rebuilt, which usually fixed the problem.

macOS is more complex, and doesn’t have a single Desktop Database, but divides its functions between several services, including LaunchServices, which associates document types with default apps in particular, and IconServices, which manages the icons to be displayed for each type. I haven’t mentioned the service which most people associate with this now, QuickLook, because that appears to serve IconServices and handles special cases, as I’ll explain.

Building the icon cache

Before showing how a document get its icon, the pre-question is how those icons get there in the first place.

Each app bundle is able to define its custom document types and their icons, and when it’s installed, iconservicesagent from /System/Library/CoreServices generates icon images to represent them, storing them in the cache at /Library/Caches/com.apple.iconservices.store alongside those defined by the system.

Errors in this process will inevitably result in errors displaying icons, but there doesn’t seem to be any way of checking what is in that cache. The folder itself is locked away from user eyes by its permissions, but contains a large number of icon images stored as isdata files by UUID. The great majority will date from the last major macOS installation, with a few added more recently as you have added apps with new document types.

Fetching the right icon

When you select a document in the Finder, a dialog, or somewhere else where you expect its icon to be shown, the Finder passes details of the document path and its type (UTI) to IconServices, to get the appropriate icon. This calls on its main service, iconservicesd (also in /System/Library/CoreServices) to check its icon cache.

Although the main icon store is locked away in /Library/Caches/com.apple.iconservices.store, there’s additional data in a folder on a path based on /private/var/folders/…/C/com.apple.iconservices, where … is an unreadable alphanumeric name. For icons used in the Dock, their cache is at /private/var/folders/…/C/com.apple.dock.iconcache

If the icon could be replaced by a QuickLook thumbnail, such as in a Finder column view, QuickLook is asked to provide that thumbnail. That in turn may be cached in /private/var/folders/…/C/com.apple.QuickLook.thumbnailcache, which is one of Apple’s new DataVaults and completely inaccessible to users.

QuickLook relies on there being an appropriate qlgenerator to create a thumbnail of that document type; if the qlgenerator is flawed or can’t cope with the document’s contents, this can easily fall over. At present, this part of the system has some rough edges. For example, if you rename a text file with a .jpeg extension so that macOS considers it’s a JPEG image, the bundled qlgenerator may simply result in the display of a busy spinner, rather than resolving to a generic JPEG document icon.

IconServices then delivers the appropriate icon back to the Finder, which displays it.

What to do when it’s broken?

The first thing to check when a document appears with the wrong icon is its type, or UTI. Among the utilities which can tell you this is my free Precize: it’s given about halfway down as Type, for example a JPEG image is given as
NSFileTypeRegular: public.jpeg

You can check UTIs using my free UTIutility. Enter the UTI in the box at the top, e.g. public.jpeg, press Return, and it will tell you what type of file it is, and the expected extensions. If the type doesn’t appear to be correct, go back to the document and try changing or adding its extension. Although macOS recognises file types by other means, this is the easiest for you to control.

If you think the extension is wrong, use UTIutility to check. Type the extension without any initial period/stop into the Extensions box and press Return. If the resulting UTI is a dynamic one starting with dyn., like dyn.age81c6x4, it means macOS doesn’t recognise that extension as a known file type.

If the extension is correct and the file type looks right too, then you need to decide whether the icon should have been shown as a QuickLook thumbnail, or a custom icon according to document type. Changing Finder view type can of course help you see that.

If a thumbnail should have been generated but it hasn’t been, the problem most probably lies in the creation of that thumbnail using its respective qlgenerator. This may be because the installed qlgenerator is out of date, or the document content is corrupt or incompatible with the format expected by the qlgenerator.

If a custom icon was expected instead, then the problem lies in IconServices itself. This might be because the app defining that document type contains incorrect information, or because the IconServices cache or store is corrupt – yes, that old problem which goes right back to the very first Mac.

After all these 35 years, and numerous bug reports, Apple still doesn’t provide any tool to rebuild the IconServices cache. You might find that restarting in Safe mode (with the Shift key held down), leaving your Mac a couple of minutes, then restarting back in normal mode, might do the trick, if you’re lucky, but as far as I know, that doesn’t force the IconServices cache to be rebuilt. Neither does resetting the SMC or NVRAM, although sometimes they’re recommended.

If all else fails, and you have to force the IconServices cache to be rebuilt, the only way seems to be to delete it at the command line. Because these caches are protected by permissions, this means using sudo and entering potentially dangerous commands, so make sure that your Mac is fully backed up before even thinking about doing this.

The command to remove the main store is
sudo rm -rfv /Library/Caches/com.apple.iconservices.store

That for the subsidiary data is
sudo find /private/var/folders/ \( -name com.apple.dock.iconcache -or -name com.apple.iconservices \) -exec rm -rfv {} \;
which includes the Dock icon cache too.

Once you have done that, you’ll need to restart and give your Mac plenty of time to rebuild the caches. You should be able to observe this in Activity Monitor, where the two iconservicesagent processes – one for root, one for the user – should be well occupied with the task.

If that worsens your problems, then you will probably have to re-install macOS, as installing a major release of macOS seems to be the only other way of getting fresh caches.

Postscript

Thanks to Michael Tsai @mjtsai who pointed out that the second command, to remove subsidiary data, requires a terminating semicolon. He explains that the -exec subcommand takes an arbitrary number of arguments, so the semicolon is needed as a terminator to separate it from the next argument to the find command itself.

(Thanks to Maxwell @mxswd for asking this question, and reviewing my answer.)