Do this with AI
Install the cms-environments-publishing skill from Contentstack agent skills and connect the Publishing Helper profile in MCP Profile Hub. Then ask your agent:
Read the publish queue for the production environment over the last 24 hours. List every item that failed or was skipped with its reason, and for each failed page entry list the referenced entries that are not published to production. Don't publish anything yet.
New to this? Set up your AI workbench first.
Publishing stuck, or references didn't publish
You click publish, the toast says it worked, and the page on your site is still old. Or the page is new, but the hero it references is missing. Or a launch was scheduled for 9:00 and at 9:15 nothing has moved. These look like three problems, but they come from the same two facts: publishing is an asynchronous job, and it only sends what you told it to send.
This guide covers the publishing problems I see most often: jobs that sit in the Publish Queue, references that didn't go live, scheduled actions that didn't fire, releases that deploy partially, unlocalizing that takes a locale off the site, and publish_details that comes back empty. It applies to the UI, the Content Management API and the CLI.
What you'll learn
How to read the Publish Queue and the job status API
Why references don't publish with their parent, and how nested reference publishing decides what to send
Why scheduled publishes and release deploys skip items
What unlocalizing does to a published locale
How to read publish_details and avoid 429s during bulk publish
Symptoms
What you see | Usually means |
|---|---|
Publish Queue shows In Queue or In Progress for a long time | The job waits for other bulk jobs in your organization, or is still working through items |
Bulk job ends in Partial Complete | Some items failed. Each item has its own status and reason |
The page is live but a referenced entry or asset returns nothing | The reference was never published to that environment and locale |
Nested reference publishing shows Skipped | That item is already published to the target environment and locale |
Workflow Stage Incomplete, Approval(s) Pending or Authorization Denied on an item | A workflow, publish rule or role blocked it, and the tree below it |
A warning icon on an entry in the Publish References modal | The entry has empty required fields and blocks its own references |
A scheduled publish never ran, or published an older version | The schedule was cancelled, failed a rule at run time, or pinned another version |
A scheduled unpublish removed a different version than the one you picked | Unpublish always removes the latest published version |
Release deploy succeeded for one environment or locale and not another | Per-item, per-environment failures. A release deploy isn't all-or-nothing |
A locale disappeared from the live site after unlocalizing | The localized copy was removed, including where it was published |
publish_details is empty or shows a UID where you expected production | Missing query parameter, wrong branch or locale, or the environment UID |
429 during a bulk publish script | Bulk actions are limited to one request per second |
Why it happens
Contentstack concept: Publishing writes one version of one entry to one (locale, environment, branch) combination. The same entry can be published in en-us on production, modified since, and still a draft in de-de. Every publish, bulk publish, scheduled publish and release deploy turns into a job, and the job reports a status per item.
Two things follow from that. First, a 200 from the publish endpoint means the job was accepted, not that the content is live. Second, a publish never guesses. It doesn't follow references unless you ask it to, it doesn't pick up a newer version than the one scheduled or added to a release, and it doesn't publish an entry that fails its workflow or publish rule.
If you are new to the three ways of publishing many things at once, read Releases, bulk publish and nested reference publishing, explained first. This guide picks up where things go wrong.
Fix it
A publish sits in the queue
Open the Publish Queue first. For bulk jobs, open the job to see each item. From the API, get the job and then its failed items:
curl "https://api.contentstack.io/v3/bulk/jobs/$JOB_ID" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN" \
-H "api_version: 3.2"
curl "https://api.contentstack.io/v3/bulk/jobs/$JOB_ID/items?status=failed" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN" \
-H "api_version: 3.2"The job's summary has success, unsuccess, skip and approvals counts. Each failed item carries publish_details.status and a failure_reason. The items endpoint returns 100 items per request, so page with skip for big jobs. Use your region's API host if your stack isn't in AWS North America.
The stack bulk task queue (GET /v3/bulk/jobs with the bulk_version: 2.0 header) filters by status number:
Value | Status |
|---|---|
1 | Waiting |
2 | In Queue |
3 | In Progress |
4 | Completed |
5 | Partial Complete |
6 | Failed |
In Queue usually means other jobs are running. Only two bulk publish jobs can be active across your organization at once, so a big job on another stack can hold yours back. In Progress with a growing total_processed is a job doing its work. A job that ends in Partial Complete is done: fix the failed items and publish only those again. Resubmitting the whole job only adds requests to a limit you share with everything else hitting the stack.
The Publish Queue keeps entry activity for 30 days. For scripts, GET /v3/publish-queue with api_version: 3.2 returns the same activity, including release deployments.
References didn't publish
Publishing a page publishes the page. If the page references a new hero, the hero stays a draft and the Delivery API returns the page with a reference to content the environment doesn't have. Depending on your query, that's an empty array, a missing field or a 404 in your frontend.
You have two fixes. Publish the referenced entries yourself, or use Publish with References (nested reference publishing), which sends the parent and its referenced entries and assets as one bulk job. From the JavaScript Management SDK:
await stack.bulkOperation().publish({
details: {
entries: [{ _content_type_uid: 'page', uid: 'blt_landing_page' }],
locales: ['en-us'],
environments: ['production'],
},
is_nested: true,
api_version: '3.2',
});Nested reference publishing has rules that explain most "it skipped my entry" reports:
It follows references up to five levels deep.
It works from the latest unpublished changes and stops at the last published version of a reference. If page A references B, B references C, and only C changed, publishing A doesn't send C. Publish B with its references, or publish C directly.
Entries already published to the target environment and locale come back as Skipped.
An entry with empty required fields isn't sent, and neither is anything below it.
An entry whose workflow stage isn't complete, or that needs approval under a publish rule, blocks itself and its references. After approval, publish again.
You only see and send entries you're allowed to publish.
It must be enabled for your organization.
When the tree is deep or shared across many pages, consider modeling changes so fewer levels hold content that changes. Modular blocks, references or global fields covers that trade-off, and Nested references empty, or error 141 covers the query side.
A scheduled publish didn't run
Start in the Publish Queue: a scheduled action shows there with its date, environment and the entry version it will publish.
It isn't in the queue. It was cancelled or rescheduled. Rescheduling happens from the Entry Status panel on the entry.
It ran and failed. If the content type uses a workflow with publish rules, the entry has to satisfy them when the schedule fires. An entry that moved back a stage after scheduling fails at run time.
It ran with an older version. The schedule publishes the version you scheduled. If an editor saved a newer version afterwards, schedule again.
It ran at the wrong hour. The effective date is the local date and time of the user who scheduled it, in the time zone they picked. Check daylight saving time if the schedule crosses a change.
Two limits to remember: you can't schedule more than 12 months ahead, and a scheduled unpublish removes the latest published version in that environment, not the version you selected. The CDN only holds one published version.
To cancel a scheduled publish, unpublish or release deployment from a script, use the queue item's UID:
curl "https://api.contentstack.io/v3/publish-queue/$QUEUE_UID/unschedule" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN" \
-H "api_version: 3.2"Yes, it's a GET. A successful call returns { "notice": "Entry unscheduled successfully." }.
A release deployed partially
A release deploy is a coordinated set of publishes, not a transaction. Items fail one by one, per environment and locale, while the rest go live. When a deploy reports failures or one environment looks wrong, check these in order:
New references. A release doesn't add the new references of an updated item, and nested reference publishing isn't supported through releases. A landing page in the release goes live without its new hero unless the hero is in the release too.
Versions. Each item is pinned to a version. "Update release items" doesn't move items to newer in-progress versions, so check the version on each item before you deploy.
Required fields. An entry with an empty required field can't be published until someone completes it.
Workflows and permissions. Publish rules are configured per environment, and roles can be limited per environment. An entry can pass for staging and fail for production.
Locales. Each item publishes one locale. If fr-fr isn't in the release, the release doesn't touch it.
Fix the failing items and deploy again. After a deploy, the items are locked, so unlock the release before you change it. The limits: 500 items per release and 25 items per add-items API request.
To roll back a deployed release, use Rollback. It creates a rollback release that restores the pre-deployment versions. You can't schedule it, and you can't roll back a rollback.
Unlocalizing took a locale off the site
Unlocalizing deletes the localized copy of an entry so the locale inherits content from its fallback locale again. If that localized copy was published, unlocalizing also takes it off the environments it was published to. Requests for that locale then return the fallback content only if you ask for it with include_fallback=true and the fallback locale is published. Otherwise the entry is gone for that locale.
To undo it, restore the entry from Trash within 14 days and publish the locale again. To avoid it, unpublish the locale on purpose first, so the effect on the site is a decision instead of a side effect. Why am I getting en-us content? explains the fallback rules.
publish_details is empty
On the Content Management API, publish_details is only included when you ask for it:
curl -G "https://api.contentstack.io/v3/content_types/page/entries/$ENTRY_UID" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN" \
-H "branch: main" \
--data-urlencode "locale=de-de" \
--data-urlencode "include_publish_details=true""publish_details": [
{
"environment": "blt0f5a9d2b3c4e5f60",
"locale": "de-de",
"time": "2026-12-01T09:00:04.112Z",
"user": "blt7a8b9c0d1e2f3a40",
"version": 4
}
]If it's still empty, the entry has no publish for that locale on that branch. Check the branch header and the locale parameter: a locale that is served through fallback has no publish of its own. The environment value is a UID. Map it to a name with GET /v3/environments before you compare it with production.
On the Delivery API, publish_details describes the publish you're reading for the environment in your request. If the entry isn't there at all, it isn't published to that environment and locale.
Bulk publish returns 429
Bulk actions are limited to one request per second, and the API reference lists 10 entries in 10 locales and 10 environments per bulk publish request. A loop that fires requests as fast as it can gets 429 responses after the first one.
Use the CLI, which batches and retries for you, and keeps logs you can retry or revert from:
csdx cm:stacks:bulk-entries \
--operation publish \
--content-types page \
--environments production \
--locales en-us \
--filter modified \
-a my-token-aliasIf you write your own script, send one request per second, wait for each job before you assume it's live, and back off when you see a 429. Fix 429 rate limit errors in builds, imports and bulk publish covers backoff and concurrency in detail.
Check that it worked
The job is clean. GET /v3/bulk/jobs/{job_id}/items?status=failed returns no items.
The Delivery API has it. Fetch the entry and its references from the CDA with the right environment and locale, and compare publish_details.time with when you published:
curl -G "https://cdn.contentstack.io/v3/content_types/page/entries/$ENTRY_UID" \
-H "api_key: $CS_API_KEY" \
-H "access_token: $CS_DELIVERY_TOKEN" \
--data-urlencode "environment=production" \
--data-urlencode "locale=en-us" \
--data-urlencode "include[]=hero"Webhooks fired. If you subscribe to publish.success and publish.fail, the webhook log shows one event per item.
The site shows it. If the CDA is right and the site isn't, the problem is caching or rebuilds, not publishing. Go to Published, but my site still shows old content.
Prevent it
Make Publish with References the default for page-like content types, and train editors on the "stops at the last published version" rule.
Before scheduling a release, list each item's references and add the new ones. Check versions after the last edit.
In CI, poll the job status after every bulk publish or release deploy, and fail the pipeline on Partial Complete or Failed.
Use releases for anything that has to go live at a moment, and keep scheduled single-entry publishes for single entries.
Unpublish a locale on purpose before you unlocalize it.
Throttle bulk scripts to one request per second, or use cm:stacks:bulk-entries.
Key takeaways
A publish response means the job was accepted. Read the job status before you call it live.
Publishing doesn't follow references unless you use nested reference publishing, and that stops at the last published version.
Releases don't add new references and don't support nested reference publishing.
Scheduled actions are re-checked against workflows when they fire, and scheduled unpublish removes the latest published version.
Unlocalizing a published locale removes it from the site.
publish_details needs include_publish_details=true on the Management API, and its environment is a UID.
Frequently asked questions
Does publishing a page also publish the entries it references?
No. A normal publish only sends the entry you selected. Use Publish with References (nested reference publishing) or publish the referenced entries yourself.
Why did nested reference publishing skip an entry I just changed?
It stops at the last published version of a reference. If an unchanged entry sits between the parent and your change, publish that entry with its references or publish the changed entry directly.
Does a release pick up references I added after creating it?
No. A release doesn't add new references of an updated item automatically, and nested reference publishing isn't supported through releases. Add every referenced entry to the release.
Why is publish_details empty when I fetch an entry from the Management API?
Either you didn't pass include_publish_details=true, or the entry has no publish for that locale on that branch. The environment in publish_details is a UID, not a name.
What do the bulk job status numbers mean?
1 is Waiting, 2 In Queue, 3 In Progress, 4 Completed, 5 Partial Complete and 6 Failed.