Troubleshoot publishing failures

When a publish does not go through, the cause is almost always one of a handful of things. This guide shows where to look and how to fix the most common problems, in order.

Who this is for

Workspace Owners, Admins, and Developers resolving a failed or stuck publish.

Start here: read the logs

The fastest way to diagnose a failure is to read the logs:

1. Open Publish Logs and find the failed job.
2. Note which stage failed — validation, GitHub commit, or deployment trigger — and read the error summary.
3. If the failure was at the deployment stage, also check Deployment Logs.

The failing stage tells you which section below to use.

GitHub commit failed

If the job failed at the GitHub commit stage, check, in order:

• The GitHub App is still installed on the repository's owner account.
• The repository is still granted to the installation.
• The target branch exists and is writable. Protected branches can block direct commits.
• The repository was not renamed, moved, or deleted.

Re-open the project's GitHub integration to confirm it still reads Connected, and reconnect if needed. See Connect GitHub.

Deployment trigger failed

If the commit succeeded but the deployment trigger failed:

• The deploy hook URL may have been revoked or regenerated in your provider — re-copy it and save it again.
• The endpoint may be temporarily unavailable; check your provider's status.
• Confirm the method is still correct in Configure a deployment trigger, and use Test Deployment Trigger.

Validation failed

If the job failed during validation (preflight), the content or its files need attention before it can commit. Re-open the content item, resolve what the log points to, and publish again.

Plan limits

Some failures are limits, not errors. If you have reached your plan's limit for published items in a month, or for scheduled items, publishing is blocked until the next period or an upgrade. See Billing, trial, and plan limits.

Retry safely

Once you have fixed the cause:

• Use the project's Publishing queue to retry the publish.
• If only the deployment trigger failed, you can retry just the deployment without recommitting.
• After a retry, confirm the new attempt in Publish Logs.

Still stuck?

If a publish keeps failing after these checks, contact us with the failed job's time and the stage that failed (never share secrets or tokens), and we can help.