Troubleshooting

Most problems fall into three buckets: the record was never built the way you thought, the artifact was never published, or the page is reading a different one than you expect.

A facet is empty

Use the record preview on the index edit screen with the ID of an element you know has a value. It shows exactly what the mapper produced, so an empty facet there means the path is wrong — usually a mistyped field handle, or a path that descends through something that is not an element.

If the preview shows the value but the listing does not, the artifact is older than the definition. Rebuild and republish.

Results are stale

Check php craft caffeine/artifact/status. If it reports records changed since the last publish, the queue has not run — or auto-update is off.

Remember the debounce: a save schedules a rebuild for 30 seconds later by default, and further saves inside that window are picked up by the same job rather than queueing more.

Nothing is published

In dev mode a page whose index has never been published throws with the exact commands to run. In production it renders empty markup and logs the reason, because a 500 on a listing page is worse than an empty one.

php craft caffeine/index/build --all
php craft caffeine/artifact/publish

Publishing says “unchanged” but the files are gone

Caffeine compares a checksum against its ledger and skips a publish that would produce identical bytes. If the files were removed outside Caffeine — a wiped web root, a fresh environment restored from a database dump — the ledger still says they are there.

php craft caffeine/artifact/publish --force exists for exactly this.

The page rearranges itself when I click a facet

That is the symptom of the two engines disagreeing, and it should not happen — it is what the shared fixture suite exists to prevent. If you see it, the most likely cause is a custom widget template that builds URLs by hand rather than through search.toggleUrl().

php craft caffeine/artifact/verify will tell you whether the published artifact still matches a fresh compile.

Refinements work without JavaScript but not with it

The runtime only intercepts links whose path matches the listing’s own. If you built a facet control as a <button>, or pointed it at a different path, it will do nothing once the runtime is loaded. Facet controls must be real links.

Counts look wrong after a refinement

Check the facet’s operator. A disjunctive (or) facet is counted with its own refinements excluded, so its siblings keep useful numbers. A conjunctive (and) facet counts against everything. If a facet shows zeroes next to everything after one click, it is probably conjunctive when it should be disjunctive.

A Pro feature stopped working

If a licence lapsed, Caffeine downgrades rather than breaks: unsupported facet types are dropped, the transport falls back to fragments, stopwords and synonyms are ignored. Your stored definitions are untouched, so renewing restores exactly what was there. The control panel keeps showing the full definition throughout.

Where to look

Caffeine logs to its own file under storage/logs, at the level set in the plugin settings. Build failures, elements that could not be mapped and publish errors all land there with the index handle in the message.