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.