For the complete documentation index, see llms.txt. This page is also available as Markdown.

Troubleshooting

Most embed failures are one of five things, and the widget's error code usually tells you which. Attach a listener before you do anything else:

builder.addEventListener('error', (e) => console.error(e.detail))

The frame is empty and nothing happens

Most likely: your origin is not in the deployment's allowlist. The browser refuses to load the editor, so nothing in your code runs and nothing reports a problem for ready-timeout milliseconds. Chrome shows "refused to connect" where the frame should be, and then the widget emits handshake-timeout.

Add your origin to the deployment's NEXT_PUBLIC_TRUSTED_HUB_ORIGINS. The list is baked in at build time, so this takes a rebuild - see Embedding and origins.

Also possible: the element has no height. An inline editor fills the box you give it, and an element with no height renders nothing. Set one.

Or you are in modal mode, which starts closed and renders nothing until you call open().

handshake-timeout

No ready signal arrived in time. Two causes, in order of likelihood:

  1. The allowlist, as above.

  2. Third-party cookies are blocked in a browser without CHIPS support. The deployment cannot store its credential, so the editor never reaches the point of reporting auth. There is no workaround from your side; the browser floors are in Embedding and origins.

Raising ready-timeout does not help with either. It only changes how long you wait to find out.

auth

The deployment reached the point of authenticating and failed. Check, in this order:

  • The security template. Revoked, expired beyond renewal, scoped to a different project, or a typo. This is the common one.

  • token. A security template is exchanged against the project token, so a mismatched pair is rejected as if the key were bad.

  • The Hub session, if you are using one - expired, or minted for a different project.

  • Cookies, again. A browser that blocks them can surface this as auth rather than handshake-timeout, depending on how far it gets.

invalid-config

Attributes that contradict each other. The editor never mounts, which is deliberate.

The usual case is sec-template without stateless. A security template authenticates nobody in particular, so it is confined to stateless mode - see Authentication.

In React this is a compile-time type error instead, because the credential props are a discriminated union.

invalid-content

Stateless: the content you passed is not a parseable template. Check that you are sending the XML string itself and not a JSON wrapper around it, and that your storage layer has not truncated or re-encoded it.

Passing an empty content is not this error - it means "the host has nothing yet", and the editor waits. That is what lets you mount the element while your fetch is in flight. Only new-template turns that wait into a document.

Text and shape layers never appear

Image layers and backgrounds render, and text is missing. The credential does not authorize rendering. POST /api/render-layers answered 401.

Text and shape layers are rasterized on the server - see How rendering works - so an unauthorized credential produces a canvas with everything except text. Check the security template's scope.

The same credential authorizes the font list and the asset picker, so a missing font list usually accompanies this.

A render URL returns 404 and no image at all

Most likely: an image layer requires a background-removed version the asset does not have. A layer carrying bg_remove="1" is rendered with fallback_master=0, which fails the whole render rather than compositing the original background - see The render URL.

Confirm it from the asset itself: its info.remove_background in the Files API is empty. Requesting the image source on its own does not tell you, because outside a template render the CDN ignores fallback_master=0 and serves the original with 200. Creating the derivative fixes it with no change to the render URL, because the 404 is not cached.

An author sees the same failure earlier, as a warning in the editor and in the variation builder, so a template that renders 404 for everyone was usually saved past that warning deliberately.

The author cannot see or add fonts

The security template needs LIST on /.studio/fonts* to see the project's custom fonts, and UPLOAD as well to import them. Anything the template cannot reach is simply absent rather than shown as an error.

Every save reports storeError

Under dam-store, the credential needs upload rights. Without a scope that allows uploads, the raw content still arrives on every save but the rendering copy never lands.

A save arrives after the editor closed

That is expected under dam-store, not a bug. A save whose upload is still in flight emits after close, with its real outcome. Keep your save listener attached, or let removing the element flush the pending save - see Storing a rendering copy.

A save closed mid-upload reports storeError, but the copy is in the DAM

Your host removed the element (or unmounted the React component) while the save was still uploading. Hide it instead, and remove it once whenSaved({ timeout: 60_000 }) resolves (needs a widget release newer than 0.7.2) - see Closing the editor during a save.

The editor opens on a different render than it saved

You are probably not round-tripping templateQuery. Without it the editor falls back to the default= attributes in the XML, which differ from the saved render whenever the query overrode any of them - the usual case for a template driven by metadata or by URL variables. See The render URL.

If you are passing it, check the known limits on that page: $locale and $layout_color are not applied on the way in, and an explicitly empty value falls back to the default rather than clearing.

Unsaved work disappeared

Assigning a new content, templateId, templateName or templateQuery reloads the editor and discards unsaved edits without prompting - the host is treated as authoritative. Watch dirtychange and ask first. See Storage modes.

A variable's binding is read-only

The variable is bound to a custom metadata key your current model does not list. The editor keeps the binding and shows it read-only rather than silently rewriting it, so a narrower model never damages a template. Send the key again to make it editable.