--- title: "Headless CMS Troubleshooting Guides" description: "Discover answers to common troubleshooting questions about Headless CMS." url: "https://www.contentstack.com/docs/headless-cms-troubleshooting/faqs" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-07-27" --- # Headless CMS Troubleshooting Guides ## Content Editing & UI Workflows ### Cannot Modify a Historical Entry Version (Versioning Behavior) When attempting to update a previously saved version of an entry, the system does not allow direct modification of that historical version. Any changes made through the CMS UI or Content Management API result in the creation of a new latest version instead of altering the selected older version. **Root Cause**  Contentstack enforces immutable versioning by design. * Each time an entry is updated, a new version is created. * Historical versions are retained as read-only snapshots for audit and rollback purposes. * The Content Management API (CMA) and CMS UI only allow updates to the current/latest entry state. * Older versions cannot be edited directly to preserve content integrity and version history accuracy. This behavior ensures traceability, audit compliance, and content recovery safety. **Resolution** Do not attempt to edit historical versions directly. If content from an older version is required: * Use the **Version History** feature in the CMS UI. * Select the required version and choose **Restore** (this creates a new latest version based on that snapshot). **For API-based workflows:** * Retrieve the latest entry version via CMA. * Apply updates to the current version only. * Allow the system to generate the next version automatically. Check the entry version number before making changes and perform an update via CMS UI or CMA. **Confirm:** * A new version number is generated. * The previous historical version remains unchanged. * The updated content exists only in the new latest version. ### Entry Version Warning Showing Older Version Warnings such as “Published before localization” or indicators of older versions appear even after publishing. **Root Cause** A Release stores a snapshot of specific entry versions. Publishing a newer version outside the Release does not automatically update the Release reference. **Resolution** 1. Open the affected Release. 2. Update the entries to their latest versions. 3. Deploy. Open the Release and confirm that all referenced entries use the latest version and that the warning is no longer displayed. ### Managing Concurrent Entry Edits Without Merge Functionality Multiple contributors working on the same entry may overwrite each other's changes because the platform does not support merging entry versions. This prevents the simultaneous consolidation of updates from different users into a single version. **Root Cause** The platform's versioning architecture is designed for linear tracking and does not include a native merge feature. **Resolution** 1. Use Workflows to manage the progression of entry edits and handoffs between users. 2. Add Field Notes to provide context or instructions to other contributors. 3. Coordinate with team members to ensure only one user is editing a specific entry version at a time. After implementing a workflow-based editing process, check the version history of an entry. If updates are saved sequentially without data loss from overwrites, the coordination strategy is effective. ### Cross-section card drag-and-drop not supported in CMS UI" Reordering card components in the CMS UI may be restricted to the section in which they are placed. This prevents moving individual cards directly from one section to another via drag-and-drop. **Root Cause** The current drag-and-drop functionality only supports reordering elements within a single section. **Resolution** 1. Move cards within their specific section using the drag handles. 2. Reorder entire sections if the project requires moving a group of components. 3. Refer to the product team to submit a feature enhancement request for cross-section dragging. After attempting to drag a card within its parent section, check the vertical order. If the card moves within its section but cannot be dropped into a different section, the behavior is expected. ### Date Field Time Settings Reset During Entry Save Saving an entry in the CMS may cause the time settings in a date field to reset or shift from the originally entered values. This prevents maintaining a fixed time independent of the user's local timezone. **Root Cause** The date field automatically adjusts its value to follow the current local timezone of the user performing the save operation. **Resolution** 1. Verify the local timezone settings of the user account performing the entry save. 2. Ensure team members are aware that saved times reflect the local timezone of the last editor. 3. Refer to upcoming product enhancements for improved handling of fixed timezone settings. After entering a specific time and saving the entry, check the date field value. If the time displays an adjustment consistent with the local timezone, the behavior is operating as currently designed. ### UID Conflicts During Content Migration to a New Stack Content migration to a new stack fails with errors indicating UID uniqueness conflicts. A content type field UID matches an existing field name, or a global field import fails due to a naming collision. **Root Cause** Contentstack enforces unique UIDs for fields within a content type and globally for global fields. During migration, if a field UID in the source stack conflicts with an existing field or global field UID in the target stack, the import fails. Common causes include: a content type has a field with the same UID as a global field already present in the target, or two fields within the same content type share a UID. **Resolution** 1. Review the migration error log to identify which UIDs are conflicting. 2. Rename conflicting field UIDs in the source content type before re-exporting. 3. Ensure global field UIDs are unique across the target stack before importing. 4. If the UID collision is between a field and a global field, rename one to resolve the conflict and update any references accordingly. 5. Re-run the migration after resolving all UID conflicts. After resolving UID conflicts, re-run the import. If the migration completes without uniqueness errors, all UIDs are compatible with the target stack. ### Required Field Validation Errors When Updating Translated Entries via CMA A translation connector or API-based workflow fails to push updated translated entries back to Contentstack. The CMA returns required field validation errors even though all required fields appear to be populated. **Root Cause** The validation error typically occurs because the file field value in the update payload is structured incorrectly. The translation connector may be passing the full asset object from the original Get Entry response instead of the required simplified format (asset UID only). Other required field validation errors can occur when the payload is missing field keys that are required by the content type schema. **Resolution** 1. Review the update payload and verify that all required fields are included with valid values. 2. For file fields specifically, ensure only the asset UID is passed: { "uid": "" } 3. For reference fields, ensure only the entry UID and content type are included, not the full resolved reference object. 4. Test the corrected payload against a single entry before running the full translation batch. After correcting the payload structure, re-run the update for a single translated entry. If it succeeds without validation errors, apply the fix to the full translation workflow. ### Entry Import vs. Create Entry API - Understanding the Overwrite Flag The overwrite flag behavior during CMA entry import is unclear. It is uncertain whether import will overwrite existing entries or create duplicates, and how it differs from the Create Entry API. **Root Cause** The CMA import endpoint and the Create Entry API are distinct operations with different behaviors. The overwrite flag in the import endpoint controls whether existing entries with matching UIDs are overwritten. Without overwrite=true, importing an entry with an existing UID will either fail or create a new entry, depending on the content type's uniqueness constraints **Resolution** * CMA Import endpoint: imports entries in bulk from a JSON export. Use overwrite=true in the request to replace existing entries that share the same UID. Without overwrite, duplicate entries may be created or conflicts may occur. * Create Entry API (POST /v3/content\_types/{uid}/entries): creates a new entry each time it is called, regardless of whether an entry with the same title or content already exists. It does not accept an overwrite flag. * To update an existing entry via API, use the Update Entry (PUT) endpoint with the entry's UID. Choose the appropriate API based on the use case: use Import with overwrite=true for bulk migration scenarios, and use the Update Entry API for targeted entry updates. ### Field Display Name and UID Blank in Content Type - Missing field_metadata Fields in a content type display blank names and UIDs in the CMS UI. The fields exist in the schema but their display values are not visible. **Root Cause** The field\_metadata property is missing from the field definitions in the content type schema. This property is required for the CMS to render field display names and other UI-level metadata. When it is absent or has invalid values, the fields appear blank in the interface. **Resolution** 1. Retrieve the content type schema via the CMA: GET /v3/content\_types/{content\_type\_uid} 2. Identify fields where the field\_metadata key is missing or empty. 3. Add the field\_metadata key with appropriate default values to each affected field. At minimum, include: { "field\_metadata": { "description": "", "default\_value": "" } } 4. Update the content type schema via: PUT /v3/content\_types/{content\_type\_uid} with the corrected schema. 5. Reload the CMS UI and confirm the field display names are now visible. After updating the schema with the field\_metadata key, reload the content type in the CMS. If field display names are now visible, the metadata has been correctly added. ### Changing a Field Data Type - Correct Process to Avoid Data Loss A customer wants to change an existing field's data type (for example, from Number to String). It is unclear whether this can be done directly and what the impact on existing content will be. **Root Cause** Directly changing a field's data type in Contentstack is not supported and will result in irreversible data loss. The existing data stored in the original field type cannot be automatically converted to the new type and will be permanently deleted. **Resolution** 1. Create a new field with the desired data type (for example, a new String field). 2. Write a script using the CMA to fetch all entries, read the value from the original Number field, and write it to the new String field. 3. Verify that all entries have been migrated correctly by spot-checking a sample of entries. 4. Once migration is confirmed, deprecate the original field (optionally remove it from the UI without deleting it immediately to allow a rollback window). 5. After full validation, delete the original field if it is no longer needed After completing the migration script and verifying entry data, confirm that the new String field contains the expected values for all entries before removing the original field. ### Unique Title Constraint Blocks Content Migration - Disable via CMA A content migration from a custom CMS fails because the target Contentstack content type enforces a unique title constraint. Source content contains duplicate titles that cannot be imported. **Root Cause** By default, the title field in Contentstack content types has unique=true, which prevents multiple entries from sharing the same title. The CMS UI does not expose an option to disable this uniqueness constraint. During migration, duplicate titles from the source system trigger validation failures. **Resolution** 1. Use the CMA to update the content type schema and set unique=false on the title field: PUT /v3/content\_types/{content\_type\_uid} with the updated schema where the title field has: { "unique": false } 2. Re-run the migration import after applying this change. 3. Optionally restore unique=true after the migration is complete if uniqueness should be enforced going forward. After setting unique=false and re-running the import, confirm that entries with duplicate titles are created successfully. Restore the uniqueness constraint after migration if required. ### PUT Request Sent to Wrong Branch - Missing Branch Header A CMA PUT request intended for a specific branch is applied to the main branch instead. The entry update appears on main rather than the intended target branch. **Root Cause** The CMA defaults all requests to the main branch when no branch header is included. Without explicitly specifying the branch in the request header, every CMA operation targets main, regardless of any branch context in the UI or the calling application. **Resolution** 1. Add the branch header to all CMA requests that should target a specific branch: branch: 2. Verify the branch UID by listing available branches: GET /v3/stacks/branches 3. Re-run the PUT request with the branch header included and confirm the update is applied to the correct branch. After adding the branch header, execute the PUT request and verify the entry is updated in the correct branch, not in main. ### Restoring Deleted Entries via CMA Script Entries have been accidentally deleted from a stack. The customer needs to restore them and wants to know whether deleted entries can be published after restoration. **Root Cause** Contentstack does not provide a native UI-based entry restoration feature. Deleted entries can be recovered by recreating them via the CMA using data from a backup or audit log. Once recreated, they are new entries and publish normally through the standard workflow. **Resolution** 1. Retrieve the entry data from a backup source (for example, a previously exported JSON file, a staging stack, or a source-of-truth external system). 2. Use the CMA Create Entry endpoint (POST /v3/content\_types/{uid}/entries) to recreate each deleted entry with the original content. 3. If the original entry UID must be preserved, include the uid field in the create payload. 4. After recreating the entries, publish them through the standard publish workflow. After recreating the entries and publishing them, verify they appear correctly in the target environment via the CDA. ### Bulk Editing Multiple Entries via a Single CMA Call Is Not Supported A request is made to update multiple entries simultaneously using a single CMA API call. No documentation appears to cover bulk entry updates in one request. **Root Cause** Bulk editing of entry content via a single CMA call is not currently supported. The CMA's bulk operations endpoint supports bulk publish, unpublish, and delete, but not bulk content updates (changing field values across multiple entries simultaneously). **Resolution** 1. Fetch all required entries using the CMA GET entries endpoint (with pagination if needed). 2. Modify the desired field values in the response payload for each entry. 3. Loop through the entries and send a separate PUT /v3/content\_types/{uid}/entries/{entry\_uid} request for each one. 4. Implement rate limiting and retry logic in the loop to stay within CMA rate limits. After implementing the per-entry update loop, run it against a small batch first to confirm the updates are applied correctly before running it at full scale. ### Which Locale to Pass in the CMA Update API - Entry Locale vs. Input Parameter Locale There is confusion about which locale value should be passed in a CMA update API call: the locale of the entry being updated, or the locale from an input parameter in the workflow. Passing the wrong locale causes unexpected behavior or errors. **Root Cause** The locale parameter in a CMA update request determines which locale version of the entry is being updated. Passing the wrong locale either creates or modifies the wrong locale version of the entry, or fails validation if the specified locale does not exist for that entry. **Resolution** 1. Always pass the locale of the specific entry version you intend to update. 2. If updating the master locale version, pass the master locale code (for example, en-us). 3. If updating a localized version, pass the exact locale code of that localized version (for example, fr-fr, de-de). 4. Do not pass the input parameter locale from an external system unless it has been validated against the locales configured in the Contentstack stack. 5. To confirm which locales exist for an entry, call: GET /v3/content\_types/{uid}/entries/{entry\_uid}/locales before updating. After confirming the correct locale code and updating the request, re-run the CMA update. If the correct locale version of the entry is updated, the locale parameter is now correctly specified. ### Workflow Status Per Entry Version Not Available via API A customer wants to retrieve the complete version history of an entry along with the workflow status for each version. No API endpoint appears to provide this combination of data. **Root Cause** Contentstack does not provide workflow status per individual version through the API. The API returns the current workflow stage of the entry, not a history of stages across versions. This data is not natively persisted in a queryable per-version format. **Resolution** The following workarounds can be used to build a workflow history: 1. Use the Audit Log API (GET /v3/audit-logs) to retrieve workflow stage change events, which include the user, timestamp, and new stage for each change. Cross-reference with version numbers to reconstruct a workflow history. 2. Configure a webhook to fire on workflow stage change events. Capture and store the payload (which includes entry UID, version, and new stage) in an external system to build a persistent per-version workflow history. 3. For ongoing tracking, log workflow status at the point of each version update in the external system. After setting up the webhook listener or integrating the Audit Log API, validate that workflow stage change events are correctly captured and linked to the corresponding entry version. ### Admin Users Bypass Workflow Stage Rules: Expected Behavior An admin user is able to change an entry's workflow stage despite strict transition rules being configured that should prevent that move. The workflow constraints appear to be ignored for this user. **Root Cause** This is expected behavior by design. Organization owners, stack owners, and stack admins automatically bypass all workflow constraints, including stage transition rules and access restrictions. Elevated admin permissions are intentionally exempt from editorial workflow controls to ensure admins can always manage content regardless of workflow state. **Resolution** No fix or configuration change is available to apply workflow constraints to organization or stack admins. To manage this by design: 1. Ensure that users who must be subject to workflow constraints are assigned standard roles (not owner or admin roles). 2. Create dedicated content editor roles with the appropriate permissions that are not exempt from workflow rules. 3. Document the admin bypass behavior for the team so editors understand why admins can make transitions that standard users cannot. Workflow stage rules will be enforced correctly for non-admin users. Only organization owners, stack owners, and stack admins bypass these constraints. ### Management Token Cannot Change Workflow Stage When Role Restrictions Are Set A CMA request to change a workflow stage using a management token returns an access denied error. The same operation works when using a user auth token. **Root Cause** Workflow stage transitions with role restrictions require the transition to be performed by a user who holds the required role. A management token is not associated with a user role — it is a stack-level credential without user identity. When role restrictions are applied to a workflow stage, the CMA validates the requester's role, and a management token cannot satisfy this check. **Resolution** Two options are available: 1. Option A - Use a user auth token: Generate an auth token from a user account that holds the required role for the workflow transition. Use this auth token instead of the management token for workflow stage change requests. 2. Option B - Remove role restrictions: If user identity is not required for the transition, remove the role restriction from the workflow stage configuration. This allows management tokens to perform the transition After applying the chosen approach, re-run the workflow stage change request. If the transition succeeds without an access denied error, the authorization requirement is satisfied. ### 422 Error on Workflow Stage Change Endpoint - Entry Requires Initial Stage First A CMA request to the workflow stage change endpoint returns a 422 error. The entry exists and the workflow is configured correctly, but the stage transition fails. **Root Cause** The /workflow endpoint can only transition an entry between workflow stages if the entry already has an initial workflow stage assigned. If the entry was created without a workflow stage (for example, programmatically via API without setting a stage), it has no current stage and the transition endpoint cannot operate on it. **Resolution** 1. First, assign the initial workflow stage to the entry using the Entry Update API (PUT /v3/content\_types/{uid}/entries/{entry\_uid}). Include the workflow stage in the update payload: { "entry": { "\_workflow": { "uid": "" } } } 2. After the initial stage is set, use the workflow stage change endpoint to perform subsequent transitions. After setting the initial stage via the Entry Update API, retry the workflow stage change endpoint. If the transition completes without a 422 error, the entry now has a valid starting stage. ### Rich Text Editor Field Behavior: Empty Default JSON vs. Null RTE Blocks Rich Text Editor (RTE) fields can appear to return unexpected values in GraphQL responses. This section covers two distinct RTE behaviors that are commonly confused: **Scenario A: Empty RTE Field Returns Default JSON Instead of Null** An empty RTE field does not return null in the GraphQL response. Instead, it returns a default JSON structure even when no content has been entered. This behavior differs from plain text fields, which return null when empty. **Root Cause** RTE fields are initialized with a default JSON structure to ensure consistent and valid output for the front-end rendering layer. This approach maintains compatibility with rich text rendering libraries that expect a defined JSON schema even for empty content. Returning an empty JSON structure rather than null is intentional behavior to prevent rendering errors. **Resolution** This is expected platform behavior and cannot be changed. To handle empty RTE fields in the front-end application: 1. Check whether the returned JSON structure represents an empty document (for example, an empty paragraph node) rather than checking for null. 2. Implement a client-side utility function that evaluates the RTE JSON structure and treats it as empty when it contains no meaningful content. 3. Do not rely on null checks for RTE fields; use content checks against the JSON structure instead. **Scenario B: RTE Blocks Return Blank or Null Despite Content Being Present** RTE Blocks appear blank or return null when queried via GraphQL or the Content Delivery API, even though content is visible in the CMS editor. **Root Cause** This can occur when the RTE field’s internal data state is stale or was not correctly committed during the last save. The CMS UI may display content that has not been fully persisted or indexed for delivery. **Resolution** 1. Open the affected entry in the CMS. 2. Make a minor edit to the RTE field - for example, add a space or retype a character - and save the entry. 3. Publish the entry to the target environment. 4. Re-run the GraphQL or CDA query and confirm the RTE content is now returned correctly. Use Scenario A guidance if the RTE field is intentionally empty and the application needs to detect that state. Use Scenario B guidance if the RTE field contains content in the CMS but returns blank or null in the API response. After applying the relevant fix, query the entry again. If the RTE field returns the expected content or the empty state is correctly handled in the application, the issue is resolved. ### Entry Version History Limited to 30 Versions - Full History Not Visible The Contentstack UI displays a maximum of 30 versions for an entry, even though the entry has been saved and updated many more times. Older versions beyond the 30-version display limit are not accessible. **Root Cause** A backend configuration that controls how publish statuses are displayed across entry versions was not enabled for the affected organization. When this configuration is disabled, the version history display is capped at a lower threshold, making it appear as though older versions do not exist. **Resolution** 1. Contact Contentstack Support and report that entry version history is limited to 30 versions. Provide the stack API key and an example entry UID. 2. Engineering will enable the backend configuration to restore full version history visibility. 3. After the configuration is enabled, reload the entry in the CMS UI and confirm that all versions beyond 30 are now visible. After the fix, verify the full version history is accessible for the affected entry and that versions can be compared and restored as expected. ### ‘Saved By’ Shows Incorrect User in Entry Version History The ‘Saved By’ field in an entry’s version history displays a user who is not the person expected to have made the change. Editors report seeing unexpected names or user IDs in the version history. **Root Cause** The ‘Saved By’ field reflects the user who saved the entry version, not the user who published it. If an entry is saved by one user and later published by another, the version history shows the saver’s identity - not the publisher’s. Additionally, automated processes (API calls, CLI operations, or automation scripts) that save entries will show their associated user identity or service account. **Resolution** 1. Distinguish between the saver and the publisher: ‘Saved By’ in version history = the user who saved that version; the publishing record in the audit log = the user who triggered the publish. 2. To identify the user behind a specific updated\_by UID shown in version history, call the Users API: GET /v3/users/{user\_uid} (requires a management token). 3. Review the Audit Log (Settings > Audit Log) for the entry to see both save and publish events with their associated users and timestamps. 4. For discrepancies caused by automated processes, review which service accounts or automation configurations have write access to the affected entries. After cross-referencing the updated\_by UID with the Users API, confirm the identity of the user who saved the version and whether the change was manual or automated. ### Entry Version Missing From History and Audit Log - Silent Revision Failure A specific version of an entry (for example, version v4) is confirmed to have been published to production, but it does not appear in the version history dropdown or in the audit log. The version appears to have been deleted or never created. **Root Cause** Investigation confirmed the version was successfully created and published to production. However, due to a silent failure at the time of creation, the version was not recorded in the revisions collection - the internal store that powers version history and audit log display. The version existed and functioned correctly in live content. The absence from version history and audit logs is caused by the revision record never being written, not by any deletion action. **Resolution** 1. Contact Contentstack Support and provide the entry UID, the missing version number, and the stack API key. Engineering can inspect the revisions collection to confirm whether the version record exists. 2. Do not attempt to recreate or overwrite the missing version - the live content is correct. The issue is limited to the history display layer. 3. If the missing version is needed for audit or compliance purposes, Engineering can provide a backend confirmation that the version was created and published at the reported time. After Engineering investigates, confirm whether the revision record can be restored to the history view, or accept the Engineering-provided confirmation as the audit record for the missing version. ### Variant Entry Data Corruption - Component Misbehavior from Modular Block Duplication A variant entry exhibits unexpected component behavior: modular blocks convert to different types unexpectedly, data sources are reset without user action, and previously deleted items reappear within the entry. The issue is blocking a project go-live. **Root Cause** The corruption was caused by a bug in the duplication logic of modular blocks when applied to variant entries. The duplication process incorrectly shared or re-used block data between the base entry and the variant, causing component conversion, data source resets, and reappearance of items that had been deleted in the variant context. **Resolution** A platform fix was deployed to correct the modular block duplication logic for variant entries. No further action is required for stacks affected by this bug after the fix is applied. 1. If similar symptoms appear (components converting types, deleted items reappearing, data source resets in variant entries), contact Contentstack Support immediately with the affected variant UID, entry UID, and stack API key. 2. Do not attempt to manually re-delete the reappearing items or re-configure components - this may compound the data state. 3. After the fix is confirmed, re-verify the variant entry content to ensure all components are in their expected state and no data corruption remains. After the platform fix, open the affected variant entry and confirm that components display correctly, deleted items do not reappear, and data sources are stable. ### Unique Validation Not Enforced Inside Multiple Group Fields A Group field marked as Multiple has fields inside it (such as key and value) with the Unique property enabled. Despite the unique constraint, duplicate key/value pairs can still be saved within the same entry. **Root Cause** The Unique validation for fields within a Multiple Group operates at the entry level, not at the group-item level. This means Contentstack checks whether the value is unique across all entries in the content type - it does not check whether the value appears more than once within the multiple group instances inside a single entry. Duplicate items within the same entry’s group instances are therefore permitted by design. **Resolution** Native uniqueness enforcement within a Multiple Group’s items is not supported. Alternatives: 1. Implement client-side validation in the editorial workflow or a UI extension that checks for duplicate items within the group before saving. 2. Use a custom App SDK extension on the field to perform real-time duplicate detection within the group instances as editors add items. 3. If unique group items are a strict business requirement, consider restructuring the data model: use a JSON custom field or a modular block where the uniqueness can be enforced programmatically via a webhook or automation. After implementing the client-side or extension-based validation, confirm that editors receive a clear message when attempting to save duplicate group items. ### Restoring Accidentally Deleted Entries and Taxonomy Terms A large number of entries or taxonomy terms were accidentally deleted - for example, by a misconfigured integration script - and need to be restored. The affected content is now missing from the CMS. **Root Cause** When entries or taxonomy terms are deleted, they are moved to the Trash (Bin) and retained for a platform-defined retention period before permanent deletion. During this window, they can be restored programmatically. **Resolution** **Restoring deleted entries from Trash:** 1. Retrieve deleted entries from the Bin: GET https://app.contentstack.com/#!/stacks/{stack\_api\_key}/recycle-bin (UI) or via the CMA: GET /v3/trash (Management API Trash endpoint). 2. Restore individual entries: POST /v3/trash/{entry\_uid}/restore. 3. For bulk restoration of many entries, use the Trash API in a script: fetch all deleted entry UIDs and iterate with restore calls. **Restoring accidentally removed taxonomy terms:** 1. If terms were removed from entries (not the taxonomy itself deleted), use the CMA to re-add taxonomy terms to affected entries: PUT /v3/content\_types/{uid}/entries/{entry\_uid} with the corrected taxonomy data. 2. If terms were deleted from the taxonomy, contact Contentstack Support - taxonomy term deletion may require backend restoration if the terms are no longer in the Trash. 3. For large-scale restorations (600+ entries), contact Contentstack Support and provide the list of affected entry UIDs and the Stack API key. Engineering can assist with bulk restoration. After restoration, verify a sample of entries are correctly restored and contain the expected data. Important: Contentstack does not provide a bulk rollback endpoint for restoring multiple deleted entries in a single API call. Each entry must be restored individually using: PUT /v3/content\_types/{content\_type\_uid}/entries/{entry\_uid}/restore?deleted=true with the entry locale in the request body. For large-scale restorations, script this call iteratively across all affected entry UIDs rather than expecting a single bulk operation. ### Bulk JSON Import via UI Creates ‘Untitled’ Entries Without Populating Fields Attempting a bulk entry import through the Contentstack UI using a JSON file results in entries being created as ‘Untitled’ with no fields populated. The import appears to succeed but the entries are empty. **Root Cause** The Contentstack UI does not support bulk entry creation via JSON import. The UI import function is designed for configuration data (content types, global fields, etc.), not for populating entry fields from JSON. When a JSON entry structure is uploaded through the UI import, it creates shell entries without mapping the JSON fields to entry field values. **Resolution** 1. Use the Contentstack CLI for bulk entry import: cs cm:stacks:import --stack-api-key {key} --data-dir {path} - this correctly maps JSON data to entry fields. 2. Alternatively, use the CMA to create entries programmatically: POST /v3/content\_types/{uid}/entries with the entry data in the request body. 3. Delete the ‘Untitled’ entries created by the failed UI import before running the CLI or CMA import to avoid duplicates. After importing via CLI or CMA, verify that a sample of entries contain the expected field values and can be published successfully. ### Workflows Disabled After CLI Import/Export Between Branches Workflows are intermittently disabled with an error stating ‘no content type selected’, even though content types were previously assigned to the workflow. The issue occurs specifically after CLI import/export operations used to migrate data between branches. **Root Cause** During CLI import operations, content type UIDs in the workflow configuration can become detached if the UIDs differ between the source and target branches. The CLI import restores the workflow schema but does not re-bind the content type references when the UIDs are mismatched or the content types do not yet exist in the target branch at import time. The workflow is created but its content type associations are empty. **Resolution** 1. After a CLI import, navigate to Settings > Workflows in the target branch and open each workflow. 2. Re-add the required content types to each workflow stage that shows ‘no content type selected’. 3. Save the workflow configuration. 4. To prevent recurrence, import content types before workflows in the CLI import sequence, ensuring content type UIDs exist in the target branch before the workflow configuration references them. 5. If using automated CLI migrations, add a post-import verification step that checks workflow configurations and re-applies content type assignments if they are missing. After re-adding content types to the workflow configuration, verify that workflow stage transitions function correctly and editorial users are assigned to the correct stages. ### Prevent Self-Approval’ Setting Not Working The ‘Prevent self-approval’ setting is configured on a publish rule, but users with direct publish permission to production can still publish entries without going through an approval step. The self-approval prevention appears to have no effect. **Root Cause** The ‘Prevent self-approval’ setting only applies when an approval step is enforced by the workflow. If the workflow does not have a stage that requires approval before the publish rule is triggered, there is nothing to prevent self-approval of - the user is publishing directly, not approving their own request. The setting is irrelevant when no approval step exists in the publishing flow. **Resolution** 1. Review the workflow configuration. Confirm whether a stage is configured that requires approval before publishing to the target environment. 2. If no approval stage exists, add one: create a workflow stage (for example, ‘Pending Approval’) that must be completed before content can be published to production. Assign approvers to this stage. 3. Enable ‘Prevent self-approval’ on the publish rule in conjunction with the approval stage. This prevents the original author from approving their own content at that stage. 4. Assign the approval permission to a different user or role from the one that originally creates or edits entries. After adding an approval stage and re-enabling ‘Prevent self-approval’, verify that authors cannot approve their own publish requests and must wait for a designated approver. ### Disabling a Publish Rule - Behavior and Scope An administrator wants to temporarily disable a publish rule without deleting it. They cannot find a disabled toggle - only a delete option is visible. They also need to confirm whether the publish rule applies to all environments or only the specified one. **Root Cause** Publish rules in Contentstack do not have a standalone enable/disable toggle separate from deletion. The way to disable a publish rule is to disable the workflow it is associated with. When a workflow is disabled, all publish rules tied to that workflow are also disabled. Additionally, publish rules are scoped per environment: a rule configured for the ‘Live’ environment applies only to that environment, leaving all other environments (such as staging) unaffected. **Resolution** 1. To disable a publish rule without deleting it: navigate to Settings > Workflows, open the workflow the publish rule is associated with, and disable the workflow using the toggle. This disables the workflow and all its publish rules. 2. To re-enable, toggle the workflow back on. 3. Regarding environment scope: if a publish rule specifies ‘Live’ as the environment, users can still publish to all other environments (staging, dev, etc.) without restriction. The rule only enforces its conditions when publishing to ‘Live’. After disabling the workflow, confirm that users can publish freely to non-production environments and that the production-environment restrictions no longer apply. ### Bulk Publish and Unpublish Failing With ‘Invalid Entry’ Error Bulk publish and unpublish operations fail with an ‘Invalid entry’ error, despite the entries being valid when published individually. The bulk job log shows ‘Untitled’ entries in the failure list. Individually publishing the same entries succeeds. **Root Cause** This was a platform-level bug in the new publishing flow. The bulk publish/unpublish path was failing to correctly resolve entry versions during the validation step, causing valid entries to be flagged as invalid. The ‘Untitled’ display in the job log was a consequence of the entry resolution failure, not an indication that the entries were actually untitled or invalid. **Resolution** A platform fix has been deployed. No configuration change is required. 1. After the fix deployment, retry the bulk publish or unpublish operation that was previously failing. 2. If the ‘Invalid entry’ error persists after the fix is confirmed deployed, contact Contentstack Support with the affected entry UIDs, the stack API key, and the bulk job ID from the failed operation. After the fix, confirm that bulk publish and unpublish operations complete successfully for the previously failing entries. ### Auto Draft Feature Causing Unexpected Draft Creation on Entry Open After enabling the Auto Draft (Auto-Save) Early Access feature, drafts are automatically created whenever any editor opens an entry, even without making changes. This disrupts the editorial workflow and is causing unexpected publish issues in the newsroom. **Root Cause** The Auto Draft Early Access feature creates a draft automatically when an entry is opened for editing. In some configurations or with certain workflow setups, this behavior was overly aggressive - creating drafts even for read-only views or in environments where the feature’s interaction with existing publish flows was not yet fully validated. **Resolution** 1. Disable the Auto Draft feature to restore normal workflow behavior: navigate to Settings > Early Access Features and toggle Auto Draft off. 2. After disabling, confirm that opening an entry no longer creates an automatic draft. 3. Before re-enabling Auto Draft in future, test it on a non-production stack to validate its interaction with existing workflows and publish rules. 4. Contact Contentstack Support to report the specific disruptive behavior observed - this feedback helps improve the feature before general release. After disabling Auto Draft, verify that editors can open entries without triggering unexpected drafts and that the publishing workflow returns to normal. ### Searching Entries for Exact http:// URLs - Using CMA Regex Query An administrator needs to find all entries containing http:// links (as opposed to https://) for a security or migration audit. The CMS UI search returns both http:// and https:// results because it does not support exact protocol matching. **Root Cause** The Contentstack UI search does not support exact-match queries for URL protocol prefixes. The UI’s text search treats http and https as similar strings. Precise pattern-based searching requires the CMA with a $regex query operator. **Resolution** 1. Use the CMA with a $regex query to find entries containing http:// (without the ‘s’): 2. GET /v3/content\_types/{uid}/entries?query={“field\_uid”:{“$regex”:“^http://”}} 3. For a broader search across all text/URL fields, run the regex query per content type and per field UID. 4. Use a management token for these CMA requests. Dedicated management tokens scoped to read-only operations are recommended for audit queries. 5. Collect the matching entry UIDs and update them programmatically using the CMA PUT endpoint to replace http:// with https://. After running the regex query, verify the result set contains only entries with http:// (not https://) and confirm the update script correctly replaces the protocol prefix in all affected entries. ### WYSIWYG HTML Mismatch Between CMS UI and Delivery API Response The HTML content in a WYSIWYG field displayed in the Contentstack UI does not match the HTML returned by the Delivery API, even though the entry is at the same version. The mismatch occurs consistently on a specific entry and environment. **Root Cause** This is a data desync issue at the platform level where the HTML content stored for delivery is out of sync with the content stored for the CMS UI rendering layer. This can occur due to a data processing anomaly during a save or publish operation. The fix requires a platform-level data repair. **Resolution** 1. Re-save the affected entry (without content changes) to trigger a re-write of the delivery data. 2. Re-publish the entry to propagate the corrected content to the delivery layer. 3. Fetch the entry via the CDA and confirm the HTML now matches the CMS UI representation. 4. If the mismatch persists after re-saving and re-publishing, contact Contentstack Support with the entry UID, environment, and stack details for a platform-level data repair. After re-saving and re-publishing the entry, verify the WYSIWYG HTML in the CDA response matches the content visible in the CMS UI. ### ‘Something Went Wrong’ Error When Accessing the Dashboard or Entries Users encounter a ‘Something went wrong’ error when navigating to the Contentstack dashboard, the entry list, or individual entries. Other users on the same stack may not be affected. **Root Cause** This error is typically caused by one of the following: a stale browser session, corrupted local cache or cookies, or a desynchronized user permission state in the authorization cache. In some cases it is triggered by a recent platform deployment that a specific browser session has not refreshed. **Resolution** 1. Clear browser cache and cookies and reload the page. 2. Open Contentstack in a new incognito or private browsing window. 3. If the error persists for a specific user, ask the Organization Owner to remove the user from the organization and re-add them. This re-syncs their permission state. 4. If the error appears after a platform deployment, Engineering may need to revert the release. Contact Contentstack Support with the stack details and timestamps. After clearing cache or re-adding the user, navigate to the affected page. If it loads correctly, the session or permission state has been refreshed. ### All Contentstack UI Pages Fail to Load - Browser-Specific Issue All Contentstack UI pages - entries, assets, and content models - fail to load for a specific user. The issue persists in incognito mode and after clearing the cache, but only in one browser. **Root Cause** A browser incompatibility, corrupted browser installation, or conflicting browser extension is preventing the Contentstack UI from rendering. This is not a platform issue when it affects only one browser. **Resolution** 1. Test the same URL in a different browser (for example, switch from Chrome to Firefox or Edge). 2. If the alternative browser works, the issue is isolated to the original browser. 3. Update or reinstall the problematic browser. 4. Disable browser extensions one by one to identify if an extension is causing the conflict. After switching browsers or reinstalling, confirm that all UI pages load correctly. ### Dashboard Not Loading and Entries Cannot Be Opened A user can see the entry list but cannot open any individual entry. Clicking an entry shows the ‘Something went wrong’ error. The dashboard also fails to load for the same user. **Root Cause** The user’s authorization state has become stale or desynchronized, typically due to a Redis cache issue in the authorization layer. This can occur after role changes, SSO sync events, or organization permission updates. **Resolution** 1. Ask the Organization Owner or Admin to switch the user’s organization role from Member to Admin and back to Member (or the reverse if they are currently an Admin). This forces a permission re-sync. 2. Alternatively, remove the user from the organization entirely and re-add them with the correct role. 3. After the role change, ask the user to log out, clear their browser cache, and log back in. After the role toggle or re-add, confirm the user can access the dashboard and open entries without errors. ### UI Not Responsive or Broken After a Platform Deployment The Contentstack UI becomes unresponsive, shows visual glitches, or fails to load pages for some users immediately after a platform update or deployment. Other users may be unaffected. **Root Cause** A cached version of the previous JavaScript bundle is being served from the browser cache after a UI revamp or feature flag rollout. The old cached scripts conflict with the newly deployed code, causing rendering failures for users whose browsers cached the previous version. **Resolution** 1. Ask affected users to perform a hard refresh (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac) or clear browser cache and reload. 2. Alternatively, open Contentstack in an incognito window, which bypasses the cache. 3. If clearing cache does not resolve the issue and multiple users are affected, contact Contentstack Support. Engineering may need to revert the deployment. After clearing cache or switching to incognito, confirm the UI loads and functions as expected. ### Entries Not Visible When Switching to a Branch - UI Cache Issue When navigating to a specific branch in the entry list, no entries are visible even though the branch contains content. Refreshing the page does not help. Switching to another branch and back resolves the display temporarily. **Root Cause** This is a UI-level caching inconsistency. The entry list view retains a stale cache from a previous branch session. No data loss has occurred - the entries exist and are accessible via the API. **Resolution** 1. Navigate away from the empty branch view to another branch or stack. 2. Return to the original branch and verify entries now appear. 3. If the issue persists, clear the browser cache and reload. After navigating away and returning, confirm that entries in the branch are now visible in the list view. ### HTML Comments in HTML RTE Not Persisting HTML comments added in the HTML RTE mode disappear when the entry is saved. The expected behavior of commenting out code using syntax does not work. **Root Cause** HTML commenting within the RTE has never been an officially supported feature. The RTE processes and sanitizes HTML on save, removing markup that does not conform to its supported element set. HTML comment syntax () falls outside the supported markup and is stripped. **Resolution** This is expected platform behavior. To store developer notes or conditionally toggle content: 1. Use a separate text field in the content type specifically for internal notes. 2. For conditional content toggling, use field visibility rules or separate fields rather than HTML comments. HTML comments cannot be reliably stored in the RTE. Use alternate content type fields for notes or metadata. ### Embedding Objects and Assets in HTML RTE The HTML RTE does not appear to support embedding entries or assets directly from the editor, while the JSON RTE supports this functionality. Customers assume the HTML RTE cannot embed objects. **Root Cause** The HTML RTE does support embedding objects, but the feature must be explicitly enabled. It is disabled by default and requires activation through the RTE’s Advanced Settings. **Resolution** 1. Open the content type in the Content Type Builder. 2. Click on the HTML RTE field to open its properties. 3. Navigate to Advanced Settings > Custom and enable the Embed toggle. 4. Save the content type. Editors can now embed entries and assets directly within the HTML RTE. After enabling the Embed toggle, open an entry and confirm the embed option is available in the HTML RTE toolbar. ### JSON RTE Embed Entries Not Appearing - Content Type Requires URL Field When attempting to embed an entry link in the JSON RTE, no entries appear in the selection dialog. The content types exist but their entries cannot be selected for embedding. **Root Cause** For a content type’s entries to be selectable for embedding as links in the JSON RTE, the content type must include a URL field. Without a URL field, the JSON RTE cannot determine where the embedded entry links to and excludes those entries from the embed selection. **Resolution** 1. Open the content type whose entries should be embeddable in the Content Type Builder. 2. Add a URL field to the content type. 3. Save the content type. 4. Reload the JSON RTE entry and attempt to embed a link again - entries from the updated content type should now appear. After adding the URL field to the content type, confirm the entries appear as selectable options in the JSON RTE embed link dialog. ### RTE Always Wraps Content in

Tags - Expected Behavior All content entered in the RTE is wrapped in

tags in the API response, even for single-line text. This causes issues with frontend rendering code that does not expect paragraph wrappers. **Root Cause** The RTE enforces

tag wrapping to ensure HTML standards compliance. Block-level elements must be wrapped in appropriate container tags for valid HTML structure. This is intentional behavior. **Resolution** Two approaches are available: 1. Strip

tags programmatically on the frontend before rendering, using a utility function that removes the wrapping tags. 2. Switch to the JSON RTE for the affected field, which provides a structured JSON output that gives the frontend full control over rendering, including the ability to render content without enforced paragraph wrappers. Choose based on whether the use case benefits from structured JSON (use JSON RTE) or needs the simplest possible fix (strip tags on frontend). ### Custom Font Sizes in the Rich Text Editor Editors want to apply custom font sizes in the RTE beyond the default heading and paragraph options. No font size control appears in the editor toolbar. **Root Cause** The standard RTE does not include a font size selector by default. Custom font sizes are available through the Fonts Marketplace app. **Resolution** 1. Navigate to the Contentstack Marketplace and install the Fonts app. 2. Configure the Fonts app with the desired font sizes and attach it to the relevant stacks. 3. Once configured, the font size controls become available within the RTE for editors. After installing and configuring the Fonts app, confirm that font size options appear in the RTE toolbar. ###