Troubleshooting
Fix the common video failures fast: stuck-on-preparing uploads, blank admin fields, 403s on signed playback, and skipped seeds.
Symptom-first fixes for the failures you are most likely to hit. Find your symptom in the left column, then apply the fix.
| Symptom | Cause | Fix |
|---|---|---|
Video stuck on preparing (status never reaches ready) | The upload polls Mux for only ~6s; a slower encode leaves the status to the video.asset.ready webhook, and that webhook never arrived — the endpoint isn't publicly reachable, or the signing secret doesn't match the dashboard (a mismatch is rejected with a 401 and a logged [payload-mux] hint, so check your server logs). The video itself is fine: playbackOptions is captured when Mux creates the asset, so a stale preparing costs you the status label, not the playback URL. | Usually nothing — an open uploader polls GET /api/mux/refresh and heals the doc, and saving it does the same. To stop it recurring, point the Mux dashboard at a publicly reachable /api/mux/webhook, and confirm MUX_WEBHOOK_SECRET (or MUX_WEBHOOK_SIGNING_SECRET) matches the dashboard's. A verified webhook logs [payload-mux] webhook verified — receiving Mux events once. In development the webhook can't reach you at all — that's expected; the refresh polling covers it. See Webhook. |
| The uploader says "Video is being encoded" and seems stuck | Encoding finishes as a webhook, and an edit view open since before it arrived has no reason to re-render — so the message stays put. In local development it's more absolute: Mux cannot reach your machine at all, so that webhook never arrives. | Nothing to do — the field polls GET /api/mux/refresh, which asks Mux directly and writes the answer, then reloads the page. That works in development with no webhook at all, and it means a missed webhook in production recovers on its own. Editing a field mid-encode may raise Payload's "another user edited this document" prompt — that other user is the refresh (or the webhook); reloading is safe. |
| Uploader field or list-view thumbnail is blank | The collection registers its admin components (uploader field, thumbnail cell) by string path, so a stale import map leaves them unresolved. | Run pnpm payload generate:importmap, then restart the dev server. |
| Signed playback returns 403, or URLs come back unsigned | The signing keys are missing. Under a signed policy each read JWT-signs the playback URLs; without the keys, signing can't happen. | Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY in the env. See Signed playback. |
Boot fails: collections.muxVideo: field(s) … are already defined by the plugin | A field you passed in collections.muxVideo.overrides.fields is named like one the plugin injects: muxUploader, source, title, assetId, status, error, duration, posterTimestamp, aspectRatio, maxWidth, maxHeight, playbackOptions. Fields append on merge, so two same-named fields would otherwise reach Payload as a bare DuplicateFieldName. A colliding field nested in a row, collapsible, or unnamed tab counts too — those share the parent's level. | Rename or remove your field. To reshape a field the plugin owns rather than add one, override the collection key that holds it. |
| Seeding is skipped with a warning | MUX_TOKEN_ID / MUX_TOKEN_SECRET are unset, so the collection is marked seedDisabled. This is expected, not a failure. | Set the credentials and re-run. The next run ingests the clips and wires the refs, with no seed-file changes. See Disabled seeds. |
Behaviors that surprise people
These are working as designed, not bugs.
Deletes propagate both ways. Deleting the Payload doc deletes the Mux asset (afterDelete), and
replacing a video's asset deletes the previous one. The reverse — a Mux-dashboard delete removing the
Payload doc — only fires through the video.asset.deleted webhook. See
The asset lifecycle.
title is unique, and deduped on upload only. When a save brings a new asset in — an upload or a
server-side ingest — a duplicate title doesn't fail: it's suffixed to stay unique, so the stored title
can differ from what was typed. When extending an upload collection, the deduped title is mirrored onto
filename. Renaming an existing, already-ready video doesn't go through that path, so a duplicate title
there fails the save with Payload's normal unique error.