Troubleshooting

No tips were written

• Is the queue running? Automatic writes are queued. Run php craft queue/run, or write them directly with php craft xplain/tips/write.
• Is project config writable here? With allowAdminChanges off, Xplain writes nothing — the utility says so. Write tips in development and deploy.
• Is the field in a layout? Tips belong to a field in a layout. A field that is not in any layout has nothing to write to.

A tip is not updating

Check its state in Utilities → Xplain. Written by a person means its text is not what Xplain wrote — even a single changed character. Clear the tip in the field layout designer and Xplain takes it back on the next write.

An author sees Xplain's tips

Either showToEveryone is on, or the author's group has the See Xplain's developer tips permission. Hand-written tips always show — that is intended.

I see ' in a tip

Craft's tip renderer encodes quotes twice inside Markdown code spans. Xplain writes code containing quotes as plain text to avoid it; a tip written by hand with quotes inside backticks will still show entities. Remove the backticks around that code.

Project config shows changes after every deploy

A plugin describer is producing text that changes between runs — see Extending. Run php craft xplain/tips/write --dry-run twice; anything listed the second time is the culprit.