Diagnosing Missing or Stale Thumbnails on ShotGrid Version Entities (On-Premise)

A Version in ShotGrid shows the generic placeholder instead of a frame preview. The thumbnail_path attribute is empty, or it points to a file that no longer exists. Re-uploading the media and refreshing the browser does nothing. This is a common failure mode in on-premise ShotGrid deployments, where thumbnail generation depends on a chain of services — the event daemon, the thumbnail generator worker, and shared storage — any of which can silently break. This guide walks through the diagnostic order that isolates the failing link fastest.

Behavior described here reflects on-premise ShotGrid installations with the event daemon and a separate thumbnail generation service. Cloud-hosted ShotGrid handles thumbnails differently, and exact log locations vary by version, so treat paths and service names as representative and confirm against your deployment's documentation.

Recognizing the condition

The symptom is consistent: Versions display a blank or placeholder thumbnail in the web UI and in ShotGrid Create/desktop clients. Checking the entity's fields shows thumbnail_path is null or references a missing file. Critically, the condition persists after re-uploading media — which tells you the problem is in the processing pipeline, not the upload itself.

Cause map

Ordered checks

Work through these in order; each check rules out a layer of the pipeline.

1. Confirm the source file is reachable. From the host running the thumbnail generator, as the service account, verify the Version's media file exists at its stored path and is readable. A simple read test (e.g., head -c 1024 /path/to/media.mov on Linux, run via sudo -u <service-account>) is enough. If this fails, stop here — nothing downstream can succeed.
2. Verify the event daemon is processing events for the site. Check that the daemon service is running and that its logs show recent version.create or version.update events. If the daemon is down or lagging, thumbnail jobs are never queued.
3. Inspect the thumbnail generator. Check service status and queue depth. A crashed worker or a queue that only grows indicates the generator itself is the failure point. Look in its logs for errors referencing the affected Version entity IDs.
4. Check the media format. Compare the file extension and codec of failing Versions against the formats your generator build supports. A corrupted file or an unusual codec (for example, a camera RAW variant or a new HEVC profile) will fail even when everything else is healthy.
5. Review recent infrastructure changes. Storage migrations, mount point renames, and service account permission tightening are the classic triggers. If thumbnails broke for all new uploads after a specific date, find what changed that day.

Fixes tied to findings

File inaccessible: Restore read access for the service account or fix the mount, then re-trigger generation by making a trivial update to the Version (for example, editing a metadata field via the web UI or API). The update emits an event that re-queues the thumbnail job.

Generator stuck or crashed: Restart the thumbnail generator service and clear any poisoned queue entries — a single corrupt file can block a worker repeatedly. Replay the missed events for the affected window if your daemon configuration supports it.

Unsupported media: Re-encode to a supported format and re-upload. Caution: re-encoding can alter timecode or color handling, so validate the converted file against the original before replacing a production Version.

Permissions or mounts changed: Correct the service account's access and validate every mount point the generator uses. Then spot-check by triggering a thumbnail on one known-broken Version before declaring the fix done.

Systemic corruption: If an entire project's thumbnails are broken (for example, after a storage move), a purge-and-rebuild of thumbnails for that project may be warranted. Do not edit thumbnail_path or thumbnail records directly in the database — this desynchronizes the asset store and creates harder problems than the one you started with.

Verifying the fix

Open an affected Version in the web UI and confirm the preview loads and thumbnail_path is populated. Then trigger a manual update on another broken Version and watch the generator logs: a new thumbnail should appear within your normal processing window. If the log shows the job being picked up but failing, the error message there is your next lead.

When to escalate

Escalate to platform engineering — with generator and daemon logs plus a list of affected entity IDs — when any of these hold: multiple projects are affected simultaneously, the generator crashes repeatedly even after queue clearing, or every new upload fails following an infrastructure change. Those patterns indicate a deployment-level fault rather than a per-asset issue, and further per-Version retries will only grow the backlog.