Live for Craft CMS

Troubleshooting

Readers aren't seeing updates

Fetch the head file yourself first. Its URL is in the <live-feed> element's data-live-config attribute (head), or in the browser's network tab.

  • 404. Snapshots aren't being written, or snapshotUrl doesn't point at snapshotPath. Check the path resolves inside the web root, then run php craft live/snapshots/rebuild <entryId>.
  • 404, and the entry isn't live yet. That is by design: files are only written while the entry is live on that site. See the next section.
  • The file exists but seq is behind. A snapshot write failed. The update is in the database and the file isn't. The cause is in the logs; the fix is a rebuild.
  • The file is current but readers aren't updating. Something in front of you is caching head.json for longer than pollInterval, or ignoring the query string. Check the response headers.
  • There's no <live-feed> on the page at all. The feed only renders for an element that has a Live field. Check the handle in your include.

Nothing appears until the entry is published

A live blog is only as public as its entry. Updates written on an entry that is scheduled, disabled, expired or a draft are kept, but the feed endpoints return 404 and no files are written. That is what makes it safe to prepare coverage ahead of time.

When the entry goes live, the first save, publish or garbage-collection run writes everything. An entry that goes live on a schedule saves nothing in Craft, so if nobody publishes, the files wait for garbage collection. Run php craft live/snapshots/collect-garbage on a cron if you schedule entries.

Publishing works but nothing is written to disk

A failed snapshot never fails a publish — on purpose — so this one is quiet on screen and loud in the logs. Search for Live could not write a snapshot. The usual causes:

  • the web root is read-only, as it often is in a container
  • snapshotPath resolves outside the web root
  • the directory is owned by a different user than PHP runs as

Fix the cause, then php craft live/snapshots/rebuild --all.

Scheduled updates never went out

php craft live/scheduled/release isn't on a cron. Nothing else releases them. Check also that the site is on Pro: on Lite, the command exits without releasing anything.

Update types are missing after a deploy

They are project config, so they arrive with your config, not with the database. Check that config/project/ was deployed and php craft up (or project-config/apply) has run.

You can't add one on production to make up for it: update types are admin-only and need allowAdminChanges, the same as entry types. Add it locally and deploy it.

An editor can see the post but can't publish

Publishing needs Publish updates and permission to edit the entry. Viewing the post only needs View live posts and permission to view the entry, so an editor with view rights on the section sees the composer and gets a 403 on ⌘↵. Grant them save rights on the section, or give the task to someone who has them.

The composer says an update is queued

That is the retry queue doing its job: the request failed and the update is kept in the browser rather than lost. It goes out when the connection comes back. If the count isn't falling and the network is fine, look for a 403 in the network tab — see the previous section.

Two editors, and one update seems to have vanished

It hasn't been overwritten — updates are separate elements, and one editor's publish can't replace another's. Check whether it was deleted (its seq will be on the removed list in head.json), and whether your template filters by type.

An edit isn't reaching readers

An edited update keeps its seq and increments rev. The shipped client watches rev in head.json and replaces the update in place. A custom front end that keys on seq alone will show the original wording forever — read rev from head.json or GraphQL and replace when it changes.

A template change doesn't show on older updates

Updates carry HTML rendered when they were published. New ones pick up a changed _update.twig straight away; published ones need php craft live/snapshots/rebuild --all.

The site got slow when the live blog got busy

Check whether SSE is on. It's off by default for exactly this reason: each connected reader holds a PHP process, and when the FPM pool is exhausted the whole site stops answering, not just the live blog. Turn it off and let readers poll. The difference to them is a few seconds; the difference to the server is staying up.

If SSE is off, check snapshots are on. Without them, every poll from every reader boots Craft.

Old feeds are still being served

A snapshot directory whose post has been deleted keeps serving to anyone with the URL until something removes it. php craft live/snapshots/collect-garbage removes the ones whose post no longer exists.

The CDN isn't being purged

  • Purging is Pro, and only runs with a driver other than None.
  • Purges go through Craft's queue, delayed by purgeThrottle seconds. If the queue isn't running, nothing is sent.
  • The head.json URL is only purged when snapshotUrl is absolute. A root-relative URL can't be purged; the entry's own URL still is.