Waterfall for Craft CMS

Troubleshooting

Start here

Open the image's own edit screen. The Watermark panel says whether the file has been marked, which profile did it, and — when nothing applies — the sentence explaining why. waterfall/doctor answers the other half: what this server can do at all.

The watermark does not appear

On transforms. Check, in order:

  1. The profile has To generated transforms ticked, and Watermark generated transforms is on in the plugin settings.
  2. The transform is actually being regenerated. Craft caches transform files by their parameters, and a file generated before you made the profile is still on disk. Clear it: php craft clear-caches/transform-indexes and delete the transform files, or edit the profile (which queues a sweep of the affected volumes).
  3. The image passes the rules — volume, file type, minimum size, named transforms, condition. craft.waterfall.explain(asset) prints one verdict per profile.

On the file itself. permanent has to be ticked and something has to trigger it: an upload, an element action, the Apply screen, or the console. Ticking the box does not go back and mark what is already there — that is what Waterfall → Apply is for.

Everywhere. If the profile is an image profile and its asset has been deleted, nothing is drawn and the profile screen says so.

It appears in the wrong colour

Almost always a palette problem, and Waterfall handles the two common cases itself:

  • A PNG saved with a colour palette — anything exported "for the web" — cannot hold a colour that is not in its palette. Waterfall promotes such images to full colour before drawing, so a red mark stays red.
  • Craft's own image saving picks a PNG sub-format from the source file, which can quantise a freshly-marked image back down to 256 colours. Waterfall writes its own PNGs as png32 for that reason.

What is left is JPEG. A JPEG is lossy: a hard-edged mark on a flat background will show compression noise around its edges at low quality. Raise Quality in the settings, or use PNG for the transform.

The transform has the watermark but the .webp variant does not

That combination means ImageOptimize generated the variant from an unmarked image, which can only happen if something changed the handler order. Waterfall registers its transform handler prepended precisely so it runs first. Check that Waterfall is enabled, clear the transforms, and regenerate. If it persists, waterfall/doctor reports what it sees of ImageOptimize.

Imager-X transforms are not watermarked

Automatic application requires Imager-X Pro — Lite does not fire the event that lets a plugin register a transformer. On Lite, name the profile in the transform:

effects: { waterfall: 'copyright' }

Also check Imager-X's own transformer setting. If it is imgix (or another service), nothing is transformed on your server at all and there is nothing for Waterfall to composite onto — use a delivery provider instead.

Text watermarks draw nothing

waterfall/doctor will say Text watermarks: GD has no FreeType support. GD compiled without FreeType cannot draw text at all. Either install ImageMagick and set imageDriver, or rebuild PHP's GD with FreeType, or use an image mark.

If the font is an uploaded asset, check the file is .ttf or .otf and that Craft's allowedFileExtensions permits it. Waterfall falls back to Lato rather than failing.

The template in a text watermark prints literally

The text is an object template, so {{ asset.title }} needs the braces. If the template throws — a field this asset does not have, a typo — Waterfall logs it and falls back to the raw string rather than failing an upload. Look for waterfall in the logs.

Restore says the backup is missing

The backup lives where Keep originals in pointed when the watermark was applied, not where it points now. If that was Waterfall's own storage folder and the folder has since been wiped — a deploy that does not carry storage/, a rebuilt container — the original is gone and the ledger row is the only record left.

For anything but a single long-lived server, point backups at a real filesystem before running a bulk apply.

An animated GIF lost its animation

Waterfall skips animated GIFs by default for exactly this reason. If Skip animated GIFs was switched off, re-encoding flattened it. Restore the original.

Assets that should not be marked keep getting marked

Three tools, in order of bluntness:

  1. Narrow the profile — volumes, file types, minimum size.
  2. Add an asset condition (Pro) for anything Craft can filter on.
  3. Add the Waterfall field (Pro) to the asset layout and set the individual asset to never.

Everything is slow after switching a profile on

Marking happens when a transform is generated, so the first page load after a change generates and composites everything at once. It settles as the cache refills.

A bulk permanent run is different — it rewrites files and is genuinely heavy. Runs above the Queue above threshold are handed to the queue for that reason; lower it if your uploads are large.

Reading the logs

Waterfall logs under the waterfall category. Every refusal that could be mistaken for a bug is logged as a warning with the profile handle in the message.

grep waterfall storage/logs/web.log | tail -50