Debugging the thumbnail subsystem in Linux Mint: a practical guide for Nemo, GIO, and .psd files

Anyone using Linux Mint (Cinnamon) has experienced the frustration of opening a folder only to find blank icons and generic placeholders inside the Nemo file manager.

Initially, common troubleshooting steps include checking Nemo preferences, purging the thumbnail cache (~/.cache/thumbnails), or reinstalling ffmpegthumbnailer. When these fail, the solution requires inspecting FreeDesktop thumbnailing rules, system calls, and MIME types.

Here is how the thumbnail subsystem works under the hood, how to generate Adobe Photoshop (.psd) previews even in paths with spaces and special characters, and how to fix malformed SVGs.

1. How Nemo generates thumbnails#

Nemo does not decode or render images directly inside its main UI process. For security, sandboxing, and desktop stability, it follows the FreeDesktop thumbnailer specification:

1. Nemo checks GIO / shared-mime-info to identify the file's exact MIME type.
2. It queries .thumbnailer instruction files located in /usr/share/thumbnailers/ or ~/.local/share/thumbnailers/.
3. It spawns the registered helper, passing the source path and a temporary output path in /tmp.
4. On success, the generated preview is cached in ~/.cache/thumbnails/normal/ or large/. If generation fails, it logs a hash in ~/.cache/thumbnails/fail/ to prevent repeated I/O stalls.

2. Adding adobe photoshop (.psd) thumbnail support#

Because PSD is a proprietary format, Linux distributions do not include native thumbnail support out of the box. Running Nemo with debug logging enabled:

nemo -q
G_MESSAGES_DEBUG=all nemo --no-desktop 2>&1 | grep -i thumbnail

Typically highlights the missing helper:

CinnamonDesktop-Message: Ignoring thumbnailer with missing binary: '/usr/lib/psdthumbnailer'

The engine: imagemagick#

ImageMagick's convert binary can parse PSD files and extract the composite preview layer:

sudo apt update
sudo apt install imagemagick

The special characters and path quoting trap#

If your project directories reside on external drives with spaces or parentheses (such as /mnt/MY_DRIVE (HD)/Projects/Design), invoking convert directly inside a .thumbnailer file breaks command parsing. The shell misinterprets the unquoted arguments, leading to silent failures.

To ensure paths are always safely encapsulated, create a lightweight wrapper script.

Step 1: Create the wrapper script#

Create /usr/local/bin/psd-thumbnailer:

sudo nano /usr/local/bin/psd-thumbnailer

Add the wrapper script to extract only the composite layer ([0]) and enforce PNG output:

#!/bin/bash
# $1 = input file
# $2 = maximum thumbnail dimension
# $3 = temporary output file

/usr/bin/convert "psd:$1[0]" -thumbnail "$2" "png:$3"

Grant executable permissions:

sudo chmod +x /usr/local/bin/psd-thumbnailer

Why [0] matters: Photoshop files often contain dozens of heavy layers. Passing [0] tells ImageMagick to extract only the composite top-level preview, preventing system lag on large multi-layer files.

Step 2: Configure the system thumbnailer rule#

Create the rule file at /usr/share/thumbnailers/psd.thumbnailer:

sudo nano /usr/share/thumbnailers/psd.thumbnailer

Add the following configuration:

[Thumbnailer Entry]
TryExec=/usr/local/bin/psd-thumbnailer
Exec=/usr/local/bin/psd-thumbnailer %i %s %o
MimeType=image/vnd.adobe.photoshop;image/x-photoshop;image/photoshop;

3. Invalid jpgs: diagnosing errors by magic bytes#

If specific .jpg files refuse to display previews, starting Nemo with G_MESSAGES_DEBUG=all may reveal:

(nemo:5241): CinnamonDesktop-WARNING **: Error creating thumbnail for file:///home/user/Downloads/photo.jpg: Erro ao interpretar o arquivo de imagem JPEG (Not a JPEG file: starts with 0x3c 0x3f)

Root cause#

Authentic JPEG files start with the hexadecimal SOI marker 0xFF 0xD8. The byte sequence 0x3c 0x3f represents <? in ASCII.

The file named .jpg was actually an HTML error page or PHP traceback saved with an image extension. The decoder rejects the file because the header violates the binary standard.

4. Malformed SVG vectors#

When vector .svg previews fail:

** (gdk-pixbuf-thumbnailer:11506): WARNING **: Could not thumbnail 'file:///mnt/storage/logo.svg': XML parse error: Extra content at the end of the document

This librsvg error occurs when trailing text exists after the root </svg> closing tag.

To clean the file via terminal:

# Truncate cleanly after the closing SVG tag
sed -i.bak '/<\/svg>/q' "/mnt/storage/logo.svg"

# Verify XML validity
xmllint --noout "/mnt/storage/logo.svg"

Maintenance checklist for desktop thumbnails#

When thumbnails fail to render:

1. Clear failed and cached previews: Nemo will not retry files that already have entries in the failure cache:

rm -rf ~/.cache/thumbnails/fail/*
rm -rf ~/.cache/thumbnails/large/*
rm -rf ~/.cache/thumbnails/normal/*
nemo -q

1. Never run Nemo with sudo: Launching sudo nemo changes ~/.cache/thumbnails ownership to root:root, breaking sandboxed thumbnail generation for standard user accounts.
2. Use wrapper scripts for CLI tools: When registering custom thumbnailers in /usr/share/thumbnailers/, encapsulate parameters inside shell wrappers with double quotes ("$1") to prevent syntax failures on directories with spaces or parentheses.

See also

Linux Troubleshooting Cinnamon: from soft resets to systemd without losing desktop control

Linux Desktop freeze post-mortem: from futex lockups to Cgroups v2 on Linux

Infrastructure How to restart the XFCE4 desktop without logging out or rebooting

This post is licensed under CC BY-NC.