With an understanding of how QuickLook provides thumbnails and previews, you can be systematic when tackling its problems, although thankfully those are infrequent if not rare.

Generic icon

By far the most common problem with QuickLook thumbnailing is when a file’s specific thumbnail isn’t shown, but a generic icon for that type of file appears instead. This has been particularly common since the release of macOS Sequoia, as that ended support for older third-party generators in qlgenerators. To be able to extend the range of types supported by thumbnailing, third-party generators must now be supplied as appexes stored in an app bundle’s PlugIns folder or similar.

To pin this down, you’ll first need to discover the UTI of the files whose icons can no longer be turned into specific thumbnails. One easy way to do that is in my free UTIutility. Type in the file’s extension, press Return and the app will tell you that file’s UTI and those it conforms to.

You next need to discover which generator handles those UTIs. The official way to do that is using the command
qlmanage -m
but that now only lists qlgenerators supplied in macOS, as qlgenerators. To see listings of others as well, open my free Mints and click on its QuickLook button.

For qlgenerators, you’re given the file UTI, the path to the qlgenerator file, and (when available) its version number, e.g.
com.adobe.pdf /System/Library/QuickLook/PDF.qlgenerator (1002.2.3)

App extensions are divided into two, first those providing Previews, and second those for Thumbnails, e.g.
com.apple.applescript.text /Applications/PreviewCode.app/Contents/PlugIns/Code Previewer.appex

If no generator handles the file’s UTI, ascend the list of UTIs it conforms with to discover which generator should attempt to. If you think an old qlgenerator is the problem now, contact the app’s developer and ask whether they intend supporting macOS with an appex replacement.

Occasionally you may come across an extension conflict, in which the same extension is used for another UTI, resulting in the wrong generator trying to create a thumbnail.

The nuclear option for any QuickLook problem is to reset its caches, using the command
qlmanage -r

Although its effects might be to slow thumbnail generation for a while, it’s unlikely to prove any more damaging.

Digging deeper

If you have to go any deeper than that, you’re going to need to capture good log extracts to enable diagnosis. As far as Icon Services, QuickLook and related features are concerned, it’s essential to disable log privacy before going any further, or you’ll be driven crazy by all those messages gutted and rendered meaningless by censorship.

Even then, log entries refer to key items such as files and folders using references that may appear opaque. Some abbreviate file names and directories as ‘B{14}1.jpg’ for BeltedGalloways1.jpg, and ‘t{5}s’ for testims, as well as referring to them by hex numbers like 0xBBDBEFDB0. Another common habit in log entries is to refer to files by their inode number, either as an ino, or in a full URL such as file:///.file/id=6571367.243284. The use of UUIDs is also common, for example as uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA.

Example thumbnail generation

This was initiated by a mouse click, following which a thumbnail isn’t immediately available from cache.

01.008113 Finder sendAction:
01.012218 com.apple.Finder | ThumbnailCache (0xbbe43cfd8, kIconified) -- Retrieve: 'B{14}1.jpg' (0xBBDBEFDB0), Container: 't{5}s' (0xBBD6F1C00), found: no
01.015014 QuickLookThumbnailingDaemon com.apple.quicklook | Enqueuing thumbnail request: <QLTGeneratorThumbnailRequest: <QLThumbnailGenerationRequest:0xc34e526c0 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xc35297760 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.MobileQuickLook-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Not started>, url: (null), item: (null), ht:0 bt:0 (low quality) client:com.apple.finder>
01.015016 QuickLookThumbnailingDaemon Cache Lookup

Following that are entries for memory and disk cache lookup, also resulting in failure, so the thumbnail has to be generated.

01.015626 QuickLookThumbnailingDaemon com.apple.quicklook | Enqueuing thumbnail request: <QLTGeneratorThumbnailRequest: <QLThumbnailGenerationRequest:0xc34e526c0 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xc35297760 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.quicklook.thumbnail.ImageExtension-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Not started>, url: (null), item: (null), ht:0 bt:0 (low quality) client:com.apple.finder>
01.017045 QuickLookThumbnailingDaemon com.apple.quicklook | <QLTGeneratorThumbnailRequest: <QLThumbnailGenerationRequest:0xc34e526c0 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xc35297760 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.quicklook.thumbnail.ImageExtension-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Not started>, url: file:///Users/howardoakley/Documents/testims/BeltedGalloways1.jpg, item: (null), ht:0 bt:0 (low quality) client:com.apple.finder> is downloaded. Trying to generate a thumbnail locally
01.017054 QuickLookThumbnailingDaemon com.apple.quicklook | About to generate a thumbnail locally from URL: file:///Users/howardoakley/Documents/testims/BeltedGalloways1.jpg

This leads to the file’s UTI type being looked up in the dictionary of those known to be handled by bundled qlgenerators. These are the log entries most important to those hunting generator problems.

01.017971 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xc352a7ae0 for 'public.jpeg' #UTI
01.018010 QuickLookSupport com.apple.quicklook | Getting 5 for 'icon flavor' from UTI 'public.image' #UTI
01.018012 QuickLookSupport com.apple.quicklook | Getting 5 for 'icon flavor' from UTI 'public.jpeg' #UTI
01.018765 QuickLookThumbnailingDaemon com.apple.quicklook | Generating thumbnail for <QLThumbnailItem: 0xc351c36c0> (size (16.0, 16.0)) with badge type 1 with extension <QLThumbnailExtension: 0xc354ec540>

That thumbnail is then entered into the store and its index.

01.036504 IconServices com.apple.iconservices | ADDING_NEW_STORE_ENTRY with UUID: FEE02B54-EE08-3F1F-90BD-8A8105536419
01.037902 iconservicesagent com.apple.iconservices | ADDED_INDEX_ITEM: B1F5E967-57DC-3A3E-9459-8DE0C14862C3
01.118704 QuickLookThumbnailingDaemon com.apple.quicklook | completing thumbnail request <QLTGeneratorThumbnailRequest: <QLThumbnailGenerationRequest:0xc34e526c0 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xc35297760 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.quicklook.thumbnail.ImageExtension-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Not started>, url: file:///Users/howardoakley/Documents/testims/BeltedGalloways1.jpg, item: (null), ht:0 bt:0 (low quality) client:com.apple.finder> in addImageData

Full details are given of the thumbnail, here 32 x 32 pixels in size, as it was for a Column view entry.

01.118961 Finder com.apple.quicklook | Received thumbnail for <QLThumbnailGenerationRequest:0xbbbafc280 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xbbe83fd80 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.MobileQuickLook-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Running>: data of length 16384, bitmap format <QLTBitmapFormat 0xbbb8c0000 s=(32, 32) bpc=8 bpp=32 bpr=128 i=8194>, error (null), image <CGImage 0xbbeb25cc0> (DP)
<<CGColorSpace 0x101cf85c0> (kCGColorSpaceICCBased; kCGColorSpaceModelRGB; sRGB IEC61966-2.1)>
headroom = 1.000000
width = 32, height = 32, bpc = 8, bpp = 32, row bytes = 128,
kCGImageAlphaPremultipliedFirst | kCGImageByteOrder32Little | kCGImagePixelFormatPacked
is mask? No, has masking color? No, has soft mask? No, has matte? No, should interpolate? Yes
01.119034 QuickLookThumbnailing com.apple.quicklook | Calling request completionBlock for <QLThumbnailGenerationRequest:0xbbbafc280 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xbbe83fd80 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.MobileQuickLook-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Finished> without error.

01.119873 QuickLookThumbnailing com.apple.quicklook | Thumbnail generation duration of 0.106 for <QLThumbnailGenerationRequest:0xbbbafc280 uuid:0AD8986E-6325-4FF1-92FD-9FD3C15D57EA BeltedGalloways1.jpg (fi:<fi:<QLCacheBasicFileIdentifier:0xbbe83fd80 ino:243284> (version: <QLThumbnailVersion m:2019-01-28 12:36:40 +0000 s:656575 vi:{length = 12, bytes = 0x54b603000000000002000000} ino:3b654 g:com.apple.MobileQuickLook-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Finished>. Most representative thumbnail generated: <QLThumbnailRepresentation:0xbbea1c120 type: Thumbnail; properties=inlinePreviewMode: 1; baseline 9223372036854775807; props = {
}>
01.124730 QuickLookThumbnailingDaemon com.apple.quicklook | Thumbnail extension generated thumbnail for <QLFileThumbnailRequest:0xc352d6210 maximumSize=(16.00, 16.00) minimumSize=(0.00,0.00) scale=2.0 item=<QLThumbnailItem: 0xc351c3940>>: reply = <QLThumbnailReply: 0xc351e4600> type:0, error = (null)
01.124744 QuickLookThumbnailingDaemon com.apple.quicklook | Operation did finish for <QLFileThumbnailRequest:0xc352d6210 maximumSize=(16.00, 16.00) minimumSize=(0.00,0.00) scale=2.0 item=<QLThumbnailItem: 0xc351c3940>>
01.124784 QuickLookSupport com.apple.quicklook | Getting 5 for 'icon flavor' from UTI 'public.jpeg' #UTI

Once in the Thumbnail Cache, loading should be very quick, typically around 0.0001 seconds from start to the thumbnail being set as displayable.

Example missing generator

This shows some of the salient log entries made when a file type doesn’t have a generator available, in this case for an IconComposer icon file.

This is most obvious from UTI dictionary lookup

00.690352 QuickLookThumbnailingDaemon com.apple.quicklook | About to generate a thumbnail locally from URL: file:///Users/howardoakley/Documents/mints%20icon/Mints.icon/
00.690897 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xb933cfce0 for 'com.apple.iconcomposer.icon' #UTI
00.690957 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xb933cfce0 for 'com.apple.package' #UTI
00.691040 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xb933cfce0 for 'public.directory' #UTI
00.691092 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xb933cfce0 for 'public.item' #UTI
00.691098 QuickLookSupport com.apple.quicklook | Caching NSNULL as icon flavor for 'public.item' #UTI
00.691100 QuickLookSupport com.apple.quicklook | Caching NSNULL as icon flavor for 'public.directory' #UTI
00.691101 QuickLookSupport com.apple.quicklook | Caching NSNULL as icon flavor for 'com.apple.package' #UTI
00.691102 QuickLookSupport com.apple.quicklook | Caching NSNULL as icon flavor for 'com.apple.iconcomposer.icon' #UTI
00.691797 QuickLookThumbnailingDaemon com.apple.quicklook | Generating thumbnail for <QLThumbnailItem: 0xb92e10500> (size (16.0, 16.0)) with badge type 1 with extension <QLThumbnailExtension: 0xb934000e0>

The resulting error refers to the missing generator, not the file whose thumbnail is being generated.

00.769110 error QuickLookThumbnailing com.apple.quicklook | Generation error for request <QLFileThumbnailRequest:0x8cb0a8140 maximumSize=(16.00, 16.00) minimumSize=(0.00,0.00) scale=2.0 item=<QLThumbnailItem: 0x8cb014dc0>> : Error Domain=NSCocoaErrorDomain Code=260 "The file couldn’t be opened because it doesn’t exist."

The solution is to generate a placeholder icon as the ‘most representative’.

00.771382 QuickLookThumbnailing com.apple.quicklook | Thumbnail generation duration of 0.093 for <QLThumbnailGenerationRequest:0xbce54aa80 uuid:E33D448A-849E-4CCA-8543-5F6B9DB532D9 Mints.icon (fi:<fi:<QLCacheBasicFileIdentifier:0xbcf48dc60 ino:254169> (version: <QLThumbnailVersion m:2025-06-17 12:42:50 +0000 s:0 vi:{length = 12, bytes = 0xd9e003000000000003000000} ino:3e0d9 g:com.apple.MobileQuickLook-1>)>) (rt:2) {16,16} (icon mode, variant 0) (badge 1) - Finished>. Most representative thumbnail generated: (null)

When that is accessed later for use in the Preview pane, that’s made clear.

02.773702 Finder com.apple.AppKit | ISImage reported a placeholder, image rep is providing a placeholder image for <ISBundleIcon 0xbd0165d10> Bundle URL: file:///System/Library/CoreServices/Finder.app/ type: (null) tag: (null) tag class: (null) digest:96BABFB5-FBB5-0662-25FA-99CA1A147F30

Once the generator has been made available, in this case by running the IconComposer app for the first time, it can be used to generate a thumbnail and preview. Note this requires the appex to be launched first.

02.409348 QuickLookSupport com.apple.quicklook | No exact match found in type dictionary 0xbd01fcf00 for 'com.apple.iconcomposer.icon' #UTI
02.409406 QuickLookSupport com.apple.quicklook | Getting <QLGenerator Package.qlgenerator> for 'Generator' from UTI 'com.apple.package' #UTI
02.409408 QuickLookSupport com.apple.quicklook | Getting <QLGenerator Package.qlgenerator> for 'Generator' from UTI 'com.apple.iconcomposer.icon' #UTI
02.676198 ExtensionFoundation com.apple.extensionkit | Extension `/Applications/Icon Composer.app/Contents/PlugIns/Icon Composer QuickLook Preview.appex/Contents/MacOS/Icon Composer QuickLook Preview` of type: `` launched.

To see almost all these log entries if you’re using LogUI, fetch all the entries for the period in question, then use its Search feature to display only those with a subsystem of com.apple.quicklook.

QuickLook, or Quick Look, is the part of macOS responsible for generating custom Thumbnails and Previews of items in the Finder and elsewhere. Although it was only introduced in 2007, with Mac OS X 10.5 Leopard, its origins go back to 1988-91 when image Thumbnails could be saved in a file’s ICN# resource. A similar system arrived in Mac OS X, and was replaced by the first version of QuickLook in 2007, which has recently undergone revision, over the period 2019-25.

Resource-based Thumbnails in Classic Mac OS were relatively straightforward. Each type of file had its own icon, an association made in the hidden Desktop database. Image and video files often overrode that default by providing their own Thumbnail image as a resource, and had to update those when the file’s data was changed. Amazingly that’s still supported in modern macOS 35 years later.

QuickLook took on the task of generating Thumbnail images, and added larger Previews in which the whole document can be inspected without opening it in an app. This came with built-in Thumbnail and Preview generation for a wide range of common document types, extending to QuickTime media including audio and video. Apps are different, though, as they use icon image (icns) files stored in their bundle’s Resources folder, harking back to Classic icon resources.

Display of Thumbnails used the QuickLook framework documented here. This enabled third-parties to extend coverage to their own document types using QuickLook generators with the extension qlgenerator. Initially, they were installed into /Library/QuickLook from each app bundle.

Unlike Spotlight indexes and document versions, QuickLook stores all its files in the current Data volume, rather than locally on individual volumes. Normally, when QuickLook generated a Thumbnail or Preview, that was stored in its cache database kept in a temporary directory in the path C/com.apple.QuickLook.thumbnailcache/. Those could give revealing insights into images and other documents accessed recently, and Wojciech Regula and Patrick Wardle discovered that, in High Sierra and earlier, it was easy for malicious software to examine that cache. Apple addressed that in macOS 10.14 Mojave by making that cache completely inaccessible.

In-memory caching of Thumbnails has also proved controversial in more recent versions of macOS. To deliver smooth scrolling of Thumbnails in the Finder’s Gallery views in particular, the Finder has taken to caching them in memory for up to two days, sometimes using several GB in the process.

I described how QuickLook Thumbnails worked in early 2019, in the days before the SSV.

When you selected a document in the Finder, a dialog, or somewhere else where you expect its icon to be shown, the Finder passed details of the document path and its type (UTI) to IconServices, to fetch the appropriate icon. This called on its main service, iconservicesd 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 was 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 was at /private/var/folders/…/C/com.apple.dock.iconcache. If the icon should 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 its protected cache at /private/var/folders/…/C/com.apple.QuickLook.thumbnailcache.

QuickLook then relied on there being an appropriate qlgenerator to create a thumbnail of that document type; if the qlgenerator was flawed or could’t cope with the document’s contents, that could easily fall over. For example, if you renamed a text file with a .jpeg extension so that macOS considered it was a JPEG image, the bundled qlgenerator might have simply resulted in the display of a busy spinner, rather than resolving to a generic JPEG document icon. IconServices should then deliver the appropriate icon back to the Finder to display it.

In macOS 10.15 Catalina (2019), Apple started replacing this system with a new framework named QuickLook Thumbnailing, documented here. That replaces qlgenerators with QuickLook preview extensions, in particular Thumbnail Extensions, as explained to developers at WWDC in 2019.

macOS 15.0 Sequoia finally removed support for third-party qlgenerators, resulting in the unfortunate loss of custom Thumbnails and Previews for document types of apps that are still reliant on qlgenerators, and haven’t yet got round to providing equivalent app extensions.

When you now select a file in a view which should result in the display of its thumbnail in the Preview pane in that window, the Finder requests it from the QuickLookThumbnailingDaemon. That queues the request until the daemon can look for the image in its memory cache. If it can’t find it there it then looks in the disk cache, first at low quality 20 x 20 icon mode. If it still can’t find it, it queues a request for a fresh thumbnail to be generated. That uses the file data together with the appropriate code to create a Thumbnail, which is then returned and cached.

There’s at least one exception to this, the directory at ~/Library/Messages/Attachments/. For files inside that, and any others for which a Thumbnail can’t be generated, a generic icon is returned as the “most representative thumbnail”.

While third parties have been replacing their old qlgenerators with modern Thumbnail and Preview extensions (appexes), macOS still provides its standard qlgenerators in /System/Library/QuickLook. Third party appexes normally come in PlugIns folders in app bundles. Mints can provide a full listing of those installed. If a document type isn’t being thumbnailed as you’d expect, the first task is to discover its type as a UTI. You can then look up which qlgenerator or appex should be responsible for generating Thumbnails or Previews of that document type using Mints. By far the most common cause at present is an old third-party qlgenerator that hasn’t been replaced by an appex.