Why Dolphin wasn't showing my Blender thumbnails

We usually browse ~/Blender/Projects in Dolphin’s compact mode. It’s a flat directory full of .blend files and the occasional reference image, and at compact icon sizes the per-file previews give us a useful glance at what’s in each scene before opening it. One evening we noticed that none of the .blend files in there had previews. Just the generic Blender file icon, all the way down. Thumbnails for .blend files normally work, so this was odd. We had no idea why, but the puzzle was interesting enough to spend the evening on. This is what we found.

The first wrong theory: file size

The natural first guess was a size cap. Dolphin has a per-protocol MaximumSize setting under [PreviewSettings] that defaults to about 5 MB for the local file protocol. A glance at ls -la showed a wide spread:

Compelling at first glance. So we checked which files actually had cached thumbnails on disk, by hashing each file’s file:// URI with MD5 and looking inside ~/.cache/thumbnails/normal/, large/, and the rest. The result killed the theory immediately:

basemeshes.blend          631 KB    OK
enemy.blend               57 MB     missing
lowpoly_hla_hz.blend      33 MB     OK
pixeloe_test.blend        110 KB    OK
reference_board.blend     430 MB    OK
staging_scene.blend       8.6 MB    missing

A 430 MB file had a cached thumbnail and an 8.6 MB file didn’t. Whatever was happening, it wasn’t a size cap. Worth doing this check first next time. The data was already on disk waiting for us, and the theory survived only because we hadn’t looked yet.

A misleading detour through the fail cache

We noticed ~/.cache/thumbnails/fail/blender/ was full of recent entries and got excited. The freedesktop thumbnail spec says consumers should record fail markers when a thumbnailer is invoked and produces nothing, and a directory full of those would be a strong signal. We picked one and read its PNG text chunks to see which file it referred to:

Thumb::URI  file:///usr/share/blender/5.1/datafiles/assets/nodes/...

The fail entries weren’t for files in Projects at all. They were for sub-assets inside Blender’s bundled asset library, written by Blender’s own asset browser, completely unrelated to our problem. Useful to know that the fail cache existed and was being populated, but a dead end for this investigation.

The save-time clue

Going back to the cached thumbnails we did have, the mtimes told us something. They weren’t “whenever Dolphin last browsed the folder.” They were exact matches for the .blend save times, down to the second:

reference_board.blend      saved 2026-05-13 15:54
large/<hash>.png           written 2026-05-13 15:54

The thumbnails weren’t being generated by Dolphin browsing the folder. They were written by Blender at save time. Blender has a preference under Preferences → Save & Load called Save Preview Images, and when enabled it deposits a preview directly into the freedesktop thumbnail cache as part of the save operation.

That explained the OK/missing split. The five OK files were all saved between 8 May and 14 May 2026. The five missing files were saved between 1 April and 2 May. Some time in early May the preference got flipped on, or a Blender update changed the default, and from that point onward saves populated the cache. Older files didn’t.

Resaving and the second wrong theory

To test it, we resaved enemy.blend (one of the missing ones) with the preference confirmed on. The cache entry appeared in large/ immediately, metadata matching the new mtime. Dolphin still showed no thumbnail.

We moved the file to /home/capacap/, resaved again. New cache entry written. Still no thumbnail.

This was the moment the investigation got harder. The cache entry was valid by every measure we could check: correct URI in the Thumb::URI chunk, correct Thumb::MTime matching the source mtime, sensible image data inside, sitting in the exact path Dolphin should look. And yet Dolphin wasn’t displaying it.

We went chasing MIME types. Blender 4.0 and onward saves .blend files compressed with zstd. The first four bytes are 28 B5 2F FD, the zstd magic, instead of the literal BLENDER that the older format used. file --mime-type reported application/zstd. xdg-mime query filetype reported application/x-blender. The two tools disagree because file does pure content-based magic, while xdg-mime uses the shared-mime-info algorithm that also weighs filename globs. KIO uses QMimeDatabase, which agrees with xdg-mime. And the blender thumbnailer plugin links to libzstd.so.1 regardless, so it can read the compressed format. So zstd wasn’t the issue, satisfying as it would have been.

The folder-icon hint

The most useful clue came as a casual aside. Looking at the parent directory in Dolphin, the folder icon for Projects was showing real Blender scene previews tiled together. Dolphin’s directorythumbnail plugin builds folder icons by aggregating previews of files inside. If those previews didn’t exist, the folder icon couldn’t show them. Yet stepping into the folder gave us nothing.

That contradiction broke the case open. The folder icon was happily using cached thumbnails that the in-folder view wasn’t.

The tier theory and a falsifiable test

The freedesktop thumbnail spec defines four size tiers: normal/ for thumbnails up to 128 pixels, large/ up to 256, x-large/ up to 512, xx-large/ up to 1024. Blender writes its save-time previews exclusively to large/, at roughly 256 by 140 pixels. Dolphin’s compact view in this configuration had PreviewSize=112, which maps to the normal/ tier.

The hypothesis: Dolphin looks only in the tier matching the requested size, and doesn’t fall back to a larger tier when its preferred one is empty.

This was easy to test cleanly. We picked one OK file, pixeloe_test.blend, took its cached large/ PNG, resized to 128 pixels wide, preserved all the Thumb:: metadata, and wrote it to ~/.cache/thumbnails/normal/ under the same MD5 hash. Then refreshed Dolphin and watched whether pixeloe_test.blend started displaying a preview while the others stayed blank.

It did. Exactly that one file. Theory confirmed.

Around the same time we zoomed Dolphin’s icons way up, well past anything we’d normally use, and previews appeared for every file in the folder. At that zoom level Dolphin requests the large/ tier directly, which was already populated by Blender. The thumbnails had been there the whole time, in the wrong tier for our zoom level.

Confirming it in the source

The honest reaction at this point was “if we can’t configure this away, we can live with it.” Fair. But before closing the case we wanted to be sure we had the mechanism right rather than a plausible just-so story.

The relevant code is in frameworks/kio/src/gui/filepreviewjob.cpp. The function setUpCaching decides which tier directory to look in based on the requested preview size and stores it in m_thumbPath. Later, slotStatFile builds the lookup path as m_thumbPath + m_thumbName and reads exactly that one file. There is no iteration over tier directories, no second attempt at a larger size, no downscale-from-larger fallback. One tier, take it or leave it.

So the behavior lives at the framework level, not the Dolphin level. Any application using KIO::PreviewJob for cache lookups inherits the same blind spot.

Why nobody seems to have reported this

Searching bugs.kde.org turned up the usual suspects and none of them matched. Bug 246050 (Dolphin doesn't show new Blender thumbnails) was about adding the blender thumbnailer plugin in 2019, RESOLVED FIXED. Bug 393015 was about percent-encoding in Thumb::URI and is also fixed. There’s an open kio-extras merge request from 2020 (!16) that touches related code on the producer side, optimising to skip creating a normal/ entry when a large/ one already exists, which if anything makes this gap more common rather than fixing it.

We suspect the issue is unreported because most thumbnailers shipped with KDE write to the requested tier on demand, and the case where an application writes its own thumbnails directly into the freedesktop cache from outside KDE is uncommon. Blender does it. Once it does, Dolphin can’t see those entries unless the user happens to set a preview size in the matching tier. There’s no error, no fail marker, no log line, just blank icons.

What stands out in retrospect

Two things worth keeping from this session.

First, the file-size theory looked airtight until we cross-referenced sizes against actual cache presence. The minute we did, it died. Verify a theory against the data you have on disk before going further with it. We knew this in principle. Doing it in practice saves time.

Second, the folder-icon observation was the single most valuable piece of evidence in the session, and it came as a passing comment, not from anything we’d asked for. A debugging partner who notices unrelated things adjacent to the question is worth a lot. The directorythumbnail aggregate behavior is technically documented if you know where to look, but it’s the kind of detail that gets framed as what the user sees rather than evidence of cache state, and we wouldn’t have thought to ask about it directly.

The bug, if filed, belongs against frameworks/kio: when FilePreviewJob finds nothing in its preferred tier, fall back to a larger one and downscale. The freedesktop spec doesn’t require producers to populate every tier and explicitly tells consumers to be prepared to downscale. KIO simply doesn’t.

For our own purposes, we’ve decided to do nothing. The previews appear at zoom levels we rarely use, and the folder icon already gives a usable hint of what’s inside. Some bugs are interesting to find and not worth fixing.