Skip to main content
Contentstack MCP profile hub is in general availability!

Guides

Our guides offer in depth best practices for getting the most out of the Contentstack platform.

Debug a failing Launch deploy with an agent
GUIDE
Level: Intermediate

Debug a failing Launch deploy with an agent

A worked example of an AI agent that finds a failed Launch deployment, reads its build log, maps the error to a cause, and redeploys after you approve.

aiagent skillsmcp...
csdx import and export failures, and how to fix them
GUIDE
Level: Intermediate

csdx import and export failures, and how to fix them

Fix csdx export and import runs that run out of heap, hang, skip global fields or taxonomies, hit 429, or report a branch merge as failed.

cliautomation
Rendering JSON RTE in React without surprises
GUIDE
Level: Intermediate

Rendering JSON RTE in React without surprises

Fix JSON RTE rendering in React, from embedded entries that render nothing to hydration errors, nested lists, custom nodes and Live Preview edit tags.

sdkheadlessreact
Image transforms that surprise you
GUIDE
Level: Intermediate

Image transforms that surprise you

Why auto=webp looks soft, format=avif gets ignored, crops stretch and replaced images stay old, with the Image Delivery API fix for each.

apiheadless
Personalize variant returns the base entry, or null
GUIDE
Level: Advanced

Personalize variant returns the base entry, or null

Fix Personalize setups that return base content or null variants, from localhost geolocation and wrong project UIDs to branch limits and cached HTML.

personalizationsdknext
Webhooks: allowlisting, signatures and disabled endpoints
GUIDE
Level: Intermediate

Webhooks: allowlisting, signatures and disabled endpoints

Fix Contentstack webhooks that get blocked, fail signature checks, arrive late or get disabled as unhealthy, with a TypeScript receiver that checks signatures.

apisecurityautomation
Publishing stuck, or references didn't publish
GUIDE
Level: Intermediate

Publishing stuck, or references didn't publish

Fix publishes stuck In Progress, references that didn't go live, scheduled publishes that never ran, partial release deploys and empty publish_details.

apiautomation
Live Preview not working? A symptom index
GUIDE
Level: Intermediate

Live Preview not working? A symptom index

Match what you see in Live Preview or Visual Editor, from a blank iframe to error_code 382, to its cause and the fix, then jump to the chapter that explains it.

visual editingsdk
GraphQL errors decoded: depth, cost and partial data
GUIDE
Level: Intermediate

GraphQL errors decoded: depth, cost and partial data

What MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED, MAX_RESOLVER_COST_EXCEEDED and other Contentstack GraphQL errors mean, why HTTP 200 can fail, and how to fix each.

apigraphql
Why am I getting en-us content? Locale fallback explained
GUIDE
Level: Intermediate

Why am I getting en-us content? Locale fallback explained

You request de-de and get English. How fallback languages, unlocalized entries, include_fallback and GraphQL fallback_locale decide which locale you get back.

i18napi
Nested references come back empty, or fail with error 141
GUIDE
Level: Intermediate

Nested references come back empty, or fail with error 141

Why referenced entries come back as bare UIDs, empty arrays or a 422 with error_code 141 from the Content Delivery API, and how to fix each cause.

apisdkcontent modeling
Fix 429 rate limit errors in builds, imports and bulk publish
GUIDE
Level: Intermediate

Fix 429 rate limit errors in builds, imports and bulk publish

Find where 429 Too Many Requests errors come from in static builds, csdx imports, bulk publish and scripts, then fix them with backoff, pacing and fewer calls.

apicliautomation
ETIMEDOUT, 5xx and timeouts from the Delivery API
GUIDE
Level: Intermediate

ETIMEDOUT, 5xx and timeouts from the Delivery API

Fix ETIMEDOUT, status 0, 502, 503 and 504 errors from the Content Delivery API with SDK retries, timeouts, keep-alive, IPv4 and a last-good-data fallback.

apisdkheadless
Custom domain stuck on Pending validation in Launch
GUIDE
Level: Intermediate

Custom domain stuck on Pending validation in Launch

Fix a Launch custom domain or certificate stuck on Pending, from DCV records added as TXT to CAA records, apex domains, nested subdomains and proxies.

headlesssecurity
Launch error codes decoded: CF005, CF1001, CF1004, CF003 and more
GUIDE
Level: Intermediate

Launch error codes decoded: CF005, CF1001, CF1004, CF003 and more

What every Contentstack Launch response error code means, which limit it hits and how to fix it, plus raw RSC payloads and the warming up screen.

headlessapinext
I published, but my site still shows old content
GUIDE
Level: Beginner

I published, but my site still shows old content

A triage guide for stale pages after publishing in Contentstack, from the wrong environment or locale to static builds, CDN caches and browser caches.

headlessapi
Fix failing Launch builds
GUIDE
Level: Intermediate

Fix failing Launch builds

A Launch deployment fails, hangs in Deploying or goes live as a 404. Match your symptom to the cause and fix env vars, Node, npm auth or the output directory.

headlessclinext
Contentstack limits on one page
GUIDE
Level: Beginner

Contentstack limits on one page

Every public Contentstack limit in one place, from API rate limits and reference depth to fields, taxonomy, assets, webhooks, Launch and the CLI.

apiheadlesscontent modeling
Write your own csdx plugin
GUIDE
Level: Advanced

Write your own csdx plugin

Build a read-only csdx stack:health command that reports entry counts, unpublished, stale and incomplete entries, then link, test and publish it.

cliautomationsdk
Set up your AI workbench for Contentstack
GUIDE
Level: Beginner

Set up your AI workbench for Contentstack

Install Contentstack agent skills in your AI tool, connect MCP Profile Hub with a narrow profile, and run your first three tasks safely.

aiagent skillsmcp
Build your first Developer Hub app
GUIDE
Level: Intermediate

Build your first Developer Hub app

Build a Contentstack Developer Hub app from scratch. Pick UI locations, use App SDK v2, call APIs with OAuth and the proxy, then host and ship it.

sdkapisecurity...
Personalize with server-side rendering at the edge
GUIDE
Level: Advanced

Personalize with server-side rendering at the edge

Resolve Personalize variants in a Launch Edge Function, render entry variants on a Next.js origin, cache per variant and track results.

personalizationsdknext
Edge functions, redirects and caching on Launch
GUIDE
Level: Intermediate

Edge functions, redirects and caching on Launch

Control what happens to a request on Launch before it reaches your app. Redirects, rewrites, edge functions, CDN caching, revalidation and logs.

headlessapinext
Safe content model changes with branches and aliases
GUIDE
Level: Intermediate

Safe content model changes with branches and aliases

Change content types on a branch, diff and merge them back with the CLI, and switch your frontend with an alias instead of a redeploy.

clicontent modelingautomation
Modular blocks, references or global fields?
GUIDE
Level: Beginner

Modular blocks, references or global fields?

A decision guide for Contentstack content models. When to use modular blocks, references, global fields or taxonomies, with worked examples.

content modelingheadless
Deploy from CI with the Launch CLI, REST API and deploy hooks
GUIDE
Level: Advanced

Deploy from CI with the Launch CLI, REST API and deploy hooks

Trigger, monitor and roll back Contentstack Launch deployments from GitHub Actions with deploy hooks, the Launch CLI plugin and the Launch REST API.

cliapiautomation
Querying content by taxonomy
GUIDE
Level: Intermediate

Querying content by taxonomy

Filter entries by taxonomy terms with the Content Delivery API and the TypeScript Delivery SDK, from a single term to hierarchies and cross-type queries.

taxonomyapisdk
Lytics use cases and technical implementation guide
GUIDE
Level: Advanced

Lytics use cases and technical implementation guide

Real-word use cases for Lytics and technical implementation guide

personalizationtaxonomy
mcp-guide.png
GUIDE
Level: Advanced

How to build your own MCP server with Contentstack's tools API

Learn how to build a custom MCP server using Contentstack Tools API: fetch tool definitions, register MCP tools, proxy calls to REST/GraphQL, and add controls.

mcpapiai...
Migrating from Contentful to Contentstack in depth
GUIDE
Level: Advanced

Migrating from Contentful to Contentstack in depth

Deep dive guide to migrate from Contentful to Contentstack using an AI-guided workflow or the @contentstack/cli-external-migrate CLI plugin.

cliautomationai
The Invisible Shield: How Contentstack Launch Protects Every Customer at Scale
GUIDE

The Invisible Shield: How Contentstack Launch Protects Every Customer at Scale

Learn how Contentstack Launch uses advanced engineering and a tiered token bucket algorithm to deliver invisible yet robust DDoS protection and rate limiting for every customer, ensuring fair resource allocation and uninterrupted service even during attacks. This guide explains the challenges of scaling protection across hundreds of organizations and the technical solutions behind Contentstack's resilient architecture.

securityheadlessapi
migration-js-ts.png
GUIDE
Level: Intermediate

Migrating from the JavaScript Delivery SDK to the TypeScript Delivery SDK

Migrate from Contentstack JavaScript Delivery SDK to the TypeScript Delivery SDK with minimal rewrites: update imports, stack, queries, caching, and utilities.

sdkapi
BlogHero-TechTalk-04.webp
GUIDE
Level: Beginner

Build a real website with Contentstack and AI

Build a real Next.js website backed by Contentstack using AI. Model content, connect via the TypeScript Delivery SDK, render pages, and deploy with Launch.

headlessaisdk...
fallback-guide.png
GUIDE
Level: Beginner

Contentstack 0 to 100 for developers

Learn Contentstack fundamentals with the Kickstart Veda Next.js starter: headless CMS concepts, setup prerequisites, preview vs delivery, and architecture.

live-preview-guide.png
GUIDE
Level: Intermediate

The Ultimate Guide to Contentstack Visual Editor

Everything you need to build bulletproof real-time preview experiences with Contentstack.

content modelingvisual editingheadless...
fallback-guide.png
GUIDE
Level: Intermediate

Building a Multi-Language Website Using Contentstack and Next.js i18n

Learn how to build a multilingual blog using Contentstack and Next.js with internationalized routing, localized content, and best practices for scalable multi-language sites. This step-by-step guide covers project setup, configuring Contentstack for multiple languages, integrating with Next.js, and optimizing for localization and SEO.

content modelingnext
fallback-guide.png
GUIDE
Level: Intermediate

Modeling navigation in Contentstack

content modelingapivisual editing
fallback-guide.png
GUIDE
Level: Advanced

Reducing API Calls to Boost Performance and Stay Within Rate Limits

Learn how a site powered by Next.js and Contentstack reduced its API calls from millions to thousands per day by leveraging CDN caching, automation, and expert implementation, resulting in improved performance and lower costs.

headlessapisdk
fallback-guide.png
GUIDE
Level: Intermediate

On-demand generation of SEO title and description using Automate

When building webpages, a common requirement is to write SEO metadata tailored to the content. An essential component of effective SEO is crafting engaging, relevant titles and descriptions that accurately represent each page’s content.

automationai
fallback-guide.png
GUIDE
Level: Advanced

Removing Stale Data from Targeting with Automate

Learn how to automate the removal of stale targeting data from Contentstack entries by defining appropriate content types and automation workflows. This guide details step-by-step processes for querying, filtering, and updating entries using webhooks or scheduled automation.

automation
fallback-guide.png
GUIDE
Level: Intermediate

Automate Recipe for Content Type Propagation

This guide demonstrates how to automate the propagation of content type changes from a source stack to a destination stack in Contentstack, including setting up triggers, validating content type existence, and conditionally updating or creating content types using automation flows.

automationcontent modeling
fallback-guide.png
GUIDE
Level: Intermediate

How to upload CSV files for bulk operations using Automate

This guide explains how to automate bulk content updates in Contentstack using CSV file uploads and the Automate feature. Learn to configure your stack, set up workflows, and build robust automation for scalable, error-resistant content operations.

automationcontent modeling
fallback-guide.png
GUIDE
Level: Intermediate

Assigning Taxonomy Terms Based on Locale

This guide demonstrates how to automatically assign taxonomy terms—such as country regions—in Contentstack based on the entry's locale using Automations and JavaScript mapping logic. It includes step-by-step instructions for setting up taxonomies, content types, and automations to streamline localization workflows.

content modeling
fallback-guide.png
GUIDE
Level: Intermediate

Automatic Translation with Automate and ChatGPT

Learn how to automate content translation in Contentstack by leveraging Automate and ChatGPT, including setup, workflow configuration, and real-world automation steps. This guide provides a step-by-step approach for seamless localization and workflow management.

content modelingautomation
⌂ Proxy