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, and only when umbracoFile is dirty. It 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
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.
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.