Operations
How save-time generation, backfills, retries, and schema ownership work, and what to check when a placeholder is missing.
Generation on save
The save handler reacts to the default Image media type when umbracoFile is dirty, or when the image is saved while its blurPlaceholder is still empty. Re-saving an image that has no placeholder yet therefore fills it straight away, without waiting for maintenance. Saves made by maintenance itself are skipped, so an image that fails to generate is not processed twice. Debug-level logs record whether each save generated a placeholder or kept the existing one. The handler clears the placeholder when the source file is cleared, invalid, or temporarily unavailable, and it writes the new value in the same media save. Nothing outside the media item changes before Umbraco persists it, so the save stays atomic.
Setting Enabled to false stops save-time generation and maintenance. It does not delete anything already stored.
Backfills and retries
Maintenance runs as an Umbraco distributed background job that checks every five minutes whether work is due. A first backfill, a changed fingerprint or an interrupted pass starts at the next check, so existing images start processing within about six minutes of startup. The scan for empty placeholders then repeats every RetryInterval; a value shorter than five minutes behaves like five. Long passes work through the library in runs of about five minutes and resume from the checkpoint at the next check, which keeps a run from being taken over by another server in a load-balanced setup. With BackfillExisting turned off, the first scan for empty placeholders waits a full RetryInterval after startup.
Backfill is fingerprinted. The package stores the last completed fingerprint separately from the media property, so a configuration change that affects the generated bytes permits exactly one regeneration pass. Between passes, maintenance only looks for empty placeholders left behind by transient failures.
The fingerprint also includes an output version. A package release that changes the generated bytes for the same settings, such as the release that stopped copying source EXIF, XMP and ICC metadata into WebP placeholders, bumps it, so the first maintenance run after the upgrade regenerates existing placeholders once. That regeneration needs a completed earlier pass. If the very first backfill is still running when you upgrade, it continues with the new encoder but only fills empty placeholders. Values it already wrote stay as they are until a later fingerprint change or a new file upload.
Maintenance checkpoints the next media-library page after finishing each page. A cancelled or interrupted pass picks up from that checkpoint instead of starting over at page zero. The package discards the cursor when its fingerprint or regeneration mode no longer matches the active configuration.
Schema ownership
The package migration owns the generated data type and property. It reuses an existing property only when that property’s data type already uses the package’s plain-string schema and read-only preview UI. The health check reports an incompatible property with the same alias, and the migration never overwrites it.
Package migrations are the source of truth for this schema. Sites that disable unattended migrations must apply the package migration during deployment. Deploy and uSync projects should exclude project-authored copies of the package-owned data type rather than maintain a second, competing definition.
Troubleshooting
No property appears
Restart the host after installing the package, then check the migration log and the health check. A conflicting blurPlaceholder property or an incompatible editor shows up as a schema compatibility error.
A value is empty
Confirm the item uses the default Image media type and that umbracoFile holds a supported image. The package clears stale output for an unsupported or corrupt input and logs it once. Transient file-system or blob-storage failures leave the property empty for the next maintenance pass to pick up.
A native hash does not render
Strip blurhash: before passing the text to a BlurHash decoder. For thumbhash:, strip the prefix and base64-decode the remaining bytes before calling ThumbHash. The backoffice preview rejects unprefixed or malformed native values rather than guessing which algorithm produced them.
Package restore fails
The package targets net10.0 and declares an Umbraco dependency range of [17.1.0,19.0.0). Use a compatible .NET SDK and make sure the configured NuGet source can reach api.nuget.org.