When to Use

Symptom-mapped diagnostic for a non-working Studio canvas. Given a user-visible failure, narrow it to the underlying cause and propose the fix. Run a Section-test pre-flight first.

Use when Studio’s canvas misbehaves with a specific symptom: “canvas is blank”, “Component Loading Error”, “canvas shows wrong composition”, “preview entry doesn’t update”, “iframe never finishes loading”. If the symptom is ambiguous, route via troubleshoot first. Do NOT use to validate a fresh install (use verify-setup). Do NOT use for authoring-quality issues: those are skill-correctness.

Auth preflight: settle the credential before the first API call. Resolve it OAuth-first per authenticate-cma: CS_OAUTH_ACCESS_TOKEN, else the Contentstack MCP’s stored session. Never ask the user for a session authtoken. If nothing resolves, or a refresh fails with 400 invalid_refresh_token, hand them ! CONTENTSTACK_REGION=<code> npx @contentstack/mcp --auth (it needs a TTY and a browser, so it cannot be run for them) and wait. 403 error_code 316 is a valid credential aimed at another org: fix the org or the api_key, do not re-authenticate.

Troubleshoot Studio Canvas Issues

Context

Studio’s canvas iframe is downstream of four moving parts: Delivery SDK auth, Live Preview’s post-message channel, the canvas-app’s React rendering, and the saved composition spec. A symptom can come from any of them. This skill maps each symptom to its root cause.

Pair with verify-setup if the user is freshly set up: verify-setup walks all four layers, troubleshoot-canvas assumes you already know the symptom.

Reference: docs/setup/troubleshoot-common-studio-issues.md (the canonical table of symptoms and their fixes).

Step 0: is the App Actually Being Served?

Do this before the section-test, before anything. Studio iframes your app. If nothing answers on that origin, every downstream symptom appears: blank canvas, “SDK Not Initialized”, “Template Did Not Load”, “localhost didn’t send any data”. None of them says “your dev server isn’t running”, and it is a routine first cause: the server was never started, it crashed, it took a different port on restart, or you’re serving vite preview on :4173 while Studio points at :5173.

# 1. Is anything listening on the port Studio targets?
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:<port>/canvas

# 2. What origin does Studio actually iframe? (must match, scheme included)
#    Sections  -> env base URL + Canvas URL
#    Templates -> env base URL + the template path
#    GET /v3/environments/<env> -> urls[].url

A connection error or a non-2xx/3xx on step 1 means stop. Start the server (or fix the port/scheme mismatch) and re-test. Only when the URL Studio targets returns content does the rest of this skill apply.

Cheap, and it costs nothing when it passes. Also re-run it after any crash, port change, or switch between npm run dev and vite preview.

Run This SECOND: the Section-Test Pre-Flight

Before reading the symptom table (especially for ”SDK Not Initialized”, blank canvas, or any popup that names the SDK as broken), run this one diagnostic. It cuts the longest debugging path from hours to seconds.

The section-test: open any Section (not a Template) in Studio. Does it render with real data?

• If YES, the SDK, the credentials, the editing handshake, the Live Preview channel, and the Delivery SDK auth are ALL working. Whatever symptom you’re seeing on a Template is downstream of the SDK. Skip the SDK / init / token rows in the table. Jump straight to troubleshoot-composition-resolution. The most common cause is the connected template’s URL match (literal URL, missing leading slash, or API-set user_specified_pattern that reverted to default, see #9 in the missing-skills audit).
• If NO (sections also fail), THEN the SDK / init / token rows below are honest. Continue to the symptom table.

Why this matters: Studio’s “SDK Not Initialized” popup is a red herring in the most common case. When a Template’s useCompositionData never resolves (URL match fails), <StudioComponent /> never mounts, Studio’s editing handshake times out, and Studio surfaces that as “SDK Not Initialized”, blaming a layer that isn’t broken. Re-running install-studio won’t help. The install is fine. The section-test rules SDK-broken in or out before you spend hours in the wrong layer.

Diagnostic tooling: inspecting a stored composition’s ui

When a row below points at the stored composition (node tree, bindings, data sources, URL metadata), fetch via the Studio API. The ui field is zlib:<base64>: a literal zlib: prefix + base64-encoded zlib-deflated JSON. Decode for read-only inspection:

// Node 18+. Save as inspect-ui.js
import zlib from "node:zlib";

function decodeUi(ui) {
  if (!ui.startsWith("zlib:")) return JSON.parse(ui);  // legacy plain-JSON fallback
  const bytes = Buffer.from(ui.slice("zlib:".length), "base64");
  return JSON.parse(zlib.inflateSync(bytes).toString("utf8"));
}

// Usage: pipe the composition JSON in on stdin, get the decoded ui on stdout
const composition = JSON.parse(await new Response(process.stdin).text());
console.log(JSON.stringify(decodeUi(composition.ui), null, 2));

# Quick CLI: fetch a composition and pipe through the decoder
curl -s "<studio-api-host>/v1/projects/<projectId>/compositions/<compositionId>" \
  -H "$CS_AUTH" -H "organization_uid: <org>" | node inspect-ui.js
# $CS_AUTH is either credential: 'authorization: Bearer <oauth>' (preferred) or
# 'authtoken: <session>'. Both work since 2026-08-25 — see authenticate-cma.

Read-only (for debugging). Do not author or modify compositions through the API. You’d lose UI-generated metadata (url_queries, etc.) that the Edit-URL modal sets behind the scenes. If you want to write a composition by hand, step back into Studio’s UI.

Task

1. Match the symptom to the canonical category using the table below. Pick the closest match: exact wording matters less than category.

2. Run the “Check first” diagnostic for that category. If it confirms the diagnosis, propose the fix. If not, run the secondary check.

3. Report the symptom you matched, then the likely cause, then the exact thing to check, then the fix. Do NOT propose more than two checks. If both come back negative, escalate to reading docs/setup/troubleshoot-common-studio-issues.md or running verify-setup.

Symptom and cause matrix

Inputs Needed From the User

1. symptom: one sentence. If the symptom doesn’t clearly match a row, ask the user to describe what they see (canvas-iframe content vs surrounding UI) before guessing.

Acceptance

This skill succeeds only when ALL of the following are true.

• The reported symptom was matched to one row in the table above.
• The “Check first” diagnostic was run (or the user was directed to run it).
• If the diagnostic confirmed the cause, the fix was applied or the user was given the exact action to take.
• If the diagnostic failed to confirm, the second-most-likely cause was offered (or escalation to verify-setup / docs/setup/troubleshoot-common-studio-issues.md was suggested).
• The user was NOT given more than two diagnostic guesses in a row. If both miss, escalate to systematic verification.

Third-Party Global-Script Overlays Inside the Canvas: How to Spot + Fix

Widget/banner overlap (OneTrust, chat bubbles) or analytics pollution is NOT this section: that’s gate-third-party-scripts, which applies the SDK’s isStudioCanvas() editor-mode contract. This section is for third-party loaders that crash with error overlays.

Symptom: the Studio canvas renders fine, but a runtime error overlay pops in the iframe: pageerror: Load error! / Failed to load lytics / net::ERR_ABORTED from kit.fontawesome.com / a next/script “Load error!” from a commerce embed. The composition renders correctly BELOW the overlay: the error isn’t from Studio.

Root cause: the app’s canvas route inherits parent layouts, and those layouts inject analytics tags / third-party embeds / global <Script>s. Many of those loaders throw new Error(...) in their onload/onerror handler when their remote asset 403s or their init misconfigures. The throw surfaces as a runtime-error overlay inside Studio’s canvas iframe. Nothing to do with Studio, everything to do with the loader running on the canvas route.

Diagnose in one minute:

1. Open the canvas route directly in a normal browser tab: http://localhost:<port><canvasPath>.
2. In DevTools, open Network and filter by “Failed” or by hostname (lytics, fontawesome, third-party CDN of your embed).
3. In DevTools, open Console: any pageerror line points at a script URL. That script is your culprit.

Fix in order of preference:

1. Isolate the canvas route from app chrome (best). Route-group / layout guard so analytics + embeds + global scripts do NOT run when the path matches */canvas. Full recipe in setup-section-preview § Canvas route isolation. This is the correct long-term shape: the canvas route should be minimal by design.
2. Patch loaders that throw. Some SDKs let you swap the throw for console.warn, e.g. Lytics jstag‘s tag-load handler can be modified to warn + return instead of throw. Keeps the tag stub on other pages that use it, kills the overlay.
3. Remove vestigial loaders. FontAwesome kits often persist in <Script> tags after the app moved to a different icon system. Grep the app for fa- class usages. If there are none, delete the kit script.
4. Prefer plain <script async> over next/script. next/script (Next.js) throws its own “Load error!” when a network error occurs. A plain async <script> fails silently to the console. Only relevant when the script can legitimately fail (marketing tags, optional embeds).

Rule of thumb: every request the canvas iframe makes that is not to the Studio SDK or your app’s own bundles is a candidate for elimination. If it doesn’t need to run under Studio’s iframe, don’t run it.

Live Preview State Resets Mid-Request: Shared Stack Instance Hazard

Symptom: resolving one composition/URL makes several internal CDA/CMA calls (a literal-URL search, a candidate-ranking search, an entry lookup), and only the FIRST of them actually uses Live Preview (rest-preview.contentstack.com, populated live_preview header, drafts visible). The rest silently fall back to the plain Delivery API (cdn.contentstack.io, empty live_preview header, published-only), with no error and no code difference between the calls. Net effect: an unpublished/draft-only composition resolves on the lucky first attempt and 404s (“Composition not found for URL: …”) the moment resolution needs a second internal query — which is the common case for anything but an exact literal-URL match.

Root cause: stack.livePreviewQuery(...) does not scope to one call. It mutates a single shared object living on the stack instance itself — _client.stackConfig.live_preview in @contentstack/delivery-sdk (node_modules/@contentstack/delivery-sdk/dist/modern/lib/stack.js), the equivalent field on the legacy contentstack v3 SDK. The actual host-switch happens centrally, in @contentstack/core‘s request layer:

// @contentstack/core/dist/esm/src/lib/request.js
if (instance.stackConfig && instance.stackConfig.live_preview) {
  const livePreviewParams = instance.stackConfig.live_preview;
  if (livePreviewParams.preview_token) {
    instance.defaults.headers.live_preview = livePreviewParams.live_preview;
  }
  if (livePreviewParams.enable && livePreviewParams.live_preview !== 'init') {
    url = 'https://' + livePreviewParams.host + url;   // only switches host here
  }
}

This reads whatever the shared stackConfig.live_preview object currently holds, at the moment each individual HTTP call fires — not a value scoped to the higher-level operation that started the fetch.

The collision: this is only a problem when TWO code paths share the SAME stack instance and have DIFFERENT live-preview intentions on the SAME request. This is exactly the shape of install-studio‘s minimal-add pattern (Studio’s stackSdk reusing an existing app’s stack). Concretely, in a Next.js App Router app:

1. Studio’s SDK (@contentstack/studio-client) reads the hash param from the incoming request’s searchQuery and calls stackSdk.livePreviewQuery(hash) before its first internal query — correctly switches that ONE call to the preview host.
2. A parent layout on the SAME request does its own unrelated data fetch (e.g. homepage data for SEO metadata) via a helper that calls stack.livePreviewQuery(live_preview ?? {}) with no override — a perfectly reasonable thing for THAT call to want (metadata generation arguably should reflect published state, not an in-progress draft). But since query.live_preview is falsy, the delivery-sdk’s own livePreviewQuery takes its reset branch and explicitly sets live_preview: "" on the SHARED object.
3. Next.js runs a page’s layout(s) and the page itself concurrently on one request. That reset can land in the gap between Studio’s first and second internal queries, wiping the hash Studio just set before its next call goes out.

Neither call site is “wrong” in isolation — each wants the correct behavior for its own purpose. The bug is architectural: the API conflates “no live preview for my call” with “no live preview for anyone sharing this object right now,” because state lives on a mutable singleton instead of being scoped per-call.

Check first: confirm it empirically rather than reasoning from source alone. Patch Node’s http/https layer to log the live_preview header on every outgoing Contentstack request (must be added before any Contentstack package’s module graph loads, so restart the dev server after adding it, not hot-reload):

// lib/debug-fetch-interceptor.js — diagnostic only, delete when done
import http from "node:http";
import https from "node:https";
const CS_HOST_PATTERN = /contentstack\.(io|com)/;
function patch(mod) {
  if (mod.__csPatched) return;
  mod.__csPatched = true;
  const originalRequest = mod.request;
  mod.request = function (...args) {
    const req = originalRequest.apply(this, args);
    const host = req.getHeader?.("host") || req.host;
    if (host && CS_HOST_PATTERN.test(host)) {
      console.log(`[cs-http] -> ${req.method} https://${host}${req.path}`);
      console.log("[cs-http] live_preview header:", req.getHeader?.("live_preview"));
    }
    return req;
  };
}
if (!globalThis.__csHttpPatched) {
  globalThis.__csHttpPatched = true;
  patch(http);
  patch(https);
}

Import it for side effects at the top of the route under test, restart the dev server (not hot-reload — module-load order matters), and trigger the failing resolution. If the logged live_preview header is populated on the first call and empty on later ones for the SAME request, this is the cause. Then grep for every other call site sharing the same stack instance: grep -rn "livePreviewQuery(" src/ app/ lib/.

Fix: give Studio’s stackSdk its own independent stack instance, separate from whatever stack the rest of the app reuses for its own content fetching. Reuse the same credentials/env vars to construct it — just not the same object. This removes the collision entirely: the rest of the app can keep calling .livePreviewQuery({}) for its own reasons on its own stack, and Studio’s hash stays untouched because it’s a different instance. See install-studio § Existing Contentstack app? Take the minimal-add branch.

Common Pitfalls

See Also

• docs/setup/troubleshoot-common-studio-issues.md: the canonical reference of symptoms and their fixes (read this if the matrix above doesn’t fit)
• verify-setup: layered smoke test, run this if you’re not sure WHICH layer is failing
• install-studio, install-live-preview: for actual reinstall steps
• register-component: for “Component Loading Error” cases involving registered components