Common problems, in roughly the order you'd hit them.

Key terms

• Canvas: the iframe Studio opens inside its builder UI to preview your content.
• StudioCanvas component: the React component (<StudioCanvas />) you mount on a dedicated route in your app. Studio loads that route inside the canvas iframe.
• Compositions: the page-level records Studio stores in Contentstack. Each composition maps a URL pattern to a set of components and a connected content type entry.

Studio is trying to open a section but doesn't know where your canvas route lives.

Fix: 1. Project → Settings → Configuration → set Canvas URL to your route path (e.g. /canvas) 2. Make sure that route exists in your app and mounts <StudioCanvas /> 3. See Section preview route

Studio can't resolve the Base URL because no Environment + Language is picked.

Fix: Project → Settings → Configuration → pick both.

Your Canvas URL is / (or empty). Studio is loading the site root.

Fix: Change Canvas URL to a dedicated path like /canvas or /studio-canvas. Add the route in your app if it doesn't exist.

Your canvas route is mounting the deprecated <StudioComponent /> instead of <StudioCanvas />. Studio detects this and overlays guidance until you switch.

Fix: in the file your project's Canvas URL points at, replace the <StudioComponent /> import + render with <StudioCanvas />. The two are not interchangeable: <StudioCanvas /> self-mounts the section preview from the URL params Studio appends to the iframe, no props needed:

import { StudioCanvas } from "@contentstack/studio-react";

export default function CanvasRoute() {
  return <StudioCanvas />;
}

The overlay disappears on the next canvas reload. See Add the section preview route for the full canvas-route guide.

The route exists but doesn't mount <StudioCanvas />.

Fix: Add the component:

import { StudioCanvas } from "@contentstack/studio-react";
export default function CanvasRoute() {
  return <StudioCanvas />;
}

The template's URL pattern doesn't match a route on your site that mounts <StudioComponent />. Studio surfaces this as a banner labelled "Template Did Not Load" on the canvas, showing the composition's UID and the URL pattern that failed to resolve, with three "Potential issues" bullet points.

Fix paths (in order of likelihood): 1. Add the matching route in your app (app/blog/[slug]/page.tsx for /blog/{{entry.url}}) 2. Edit the template's URL pattern in Studio → click the pencil icon in the canvas toolbar → Edit URL modal (see Connected content type → Editing the URL) 3. Confirm the route mounts <StudioComponent /> and not <StudioCanvas /> (they're not interchangeable, see Canvas iframe issues above)

For the success counterpart (what a correctly-routed deployed template looks like at its real visitor URL), see Save vs Deploy → Deploy.

The connected entry doesn't have the data the template binds to.

Fix: Switch the Preview Entry from the canvas toolbar (the ⇄ swap icon) to an entry that has the fields populated. Or populate the current entry's fields in Contentstack.

Live Preview isn't initialised, or onEntryChange isn't wired to your render.

Fix: 1. Confirm ContentstackLivePreview.init({ … }) runs at app boot 2. Wire onEntryChange to your render or refetch: ts useEffect(() => { ContentstackLivePreview.onEntryChange(refetchSpec); }, [refetchSpec]); 3. Make sure your stack has Live Preview enabled stack-wide (Stack → Settings → Visual Experience → General) 4. Check the Preview Token in your .env.local matches the one on Contentstack 5. See Install Live Preview

clientUrlParams.host is wrong for your region.

Fix: Match it to your region's app host (US: app.contentstack.com, EU: eu-app.contentstack.com, etc.). See Install Live Preview → Non-US regions.

Stack API Key or Delivery Token is wrong, expired, or not set.

Fix: 1. Re-copy from Stack → Settings → Tokens → the Delivery Token edit screen 2. Make sure your .env.local has the right values 3. Restart your dev server, as env vars are read at boot

The content type UID is wrong, or doesn't exist in the stack.

Fix: Check Contentstack → Content Models → your CT → UID and pass that exact value to stack.contentType("...").

The composition's connected content type UID in studioSdk.init doesn't match what Studio is writing into.

Fix: Confirm studioSdk.init({ contentTypeUid: "..." }) matches the Compositions CT in your stack (Project → Settings → General → Stack Connection).

You wired the SDKs (install-studio is done) but no Studio project exists yet: the compositions content type hasn't been provisioned into your stack.

This is the expected error for the "installed but no project yet" state. It is not a broken install.

Fix: 1. Create the Studio project in app.contentstack.com (Studio → New Project → link your stack). Provisioning creates the compositions content type. 2. Until a composition is published on a route you're hitting, wrap the fetch in try/catch and render a "no composition yet" placeholder (the 422 disappears once any composition is published).

The contentTypeUid value passed to studioSdk.init doesn't match the provisioned UID.

Fix: 1. Open Studio → Project → Settings → Configuration → check "Composition Content Type". 2. If the UID isn't compositions, set <PREFIX>_CONTENTSTACK_STUDIO_CONTENT_TYPE=<uid> in .env.local and pass that value to studioSdk.init({ contentTypeUid: "<uid>" }).

Components are registered after Studio's canvas iframe loads, so it doesn't see them.

Fix: Call registerComponent / registerComponents before the canvas mounts. The cleanest way is to register at app boot, in the same module that imports @/lib/contentstack:

// src/lib/contentstack.ts
import { studioSdk, registerComponents } from "@contentstack/studio-react";
import { components } from "@/studio/components";

studioSdk.init({ … });
registerComponents(components);

The default Suspense fallback is null. Provide your own:

import { Suspense } from "react";

function PaletteFallback() {
  return <div className="loading-card">Loading…</div>;
}

// Wrap your StudioComponent / StudioCanvas with a custom Suspense if you need a global fallback.

(Today the SDK uses <Suspense fallback={null}> internally; wrap your top-level render in your own Suspense to provide a different fallback for the canvas.)

Either studioSdk.init isn't called, or it's called after you call useCompositionData.

Fix: Init must run before any hook reads the SDK. The safest place is a shared module imported at app boot: src/lib/contentstack.ts.

You called studioSdk.init without passing the Delivery SDK instance.

Fix:

import Contentstack from "@contentstack/delivery-sdk";
import { studioSdk } from "@contentstack/studio-react";

const stack = Contentstack.stack({ … });
studioSdk.init({ stackSdk: stack, contentTypeUid: "compositions" });

Before opening a support issue, run through these checks:

• [ ] Browser console: open DevTools → Console. Note any errors, especially studioSdk not initialised, 401, 422, or hydration warnings.
• [ ] Network tab: filter by XHR/Fetch. Check that content-type and composition requests return 200. A 401 means wrong credentials; a 422 means missing or mismatched content type.
• [ ] .env.local credentials: confirm CS_API_KEY, CS_DELIVERY_TOKEN, CS_PREVIEW_TOKEN, and CS_ENVIRONMENT are set and match the values in Stack → Settings → Tokens. Restart your dev server after any .env.local change.
• [ ] Canvas URL in Studio: Project → Settings → Configuration. Confirm the Canvas URL path matches the route in your app that mounts <StudioCanvas />.
• [ ] Environment per-locale Base URL: Stack → Settings → Environments → your environment → check the URL for your locale is non-empty and matches your dev origin (e.g. http://localhost:5173).

If you've worked through this page and the canvas still doesn't render, open an issue with:

• What you see (error text, screenshots if helpful)
• Which layer failed (Delivery / Live Preview / Studio SDK / canvas route / Studio project)
• Browser console output during the failure

That triages fast.