> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/troubleshooting.md).

# 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:

```js
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](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md).

**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](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md).

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](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md).

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](https://docs.scaleflex.com/developers-headless/studio/template-builder/how-rendering-works.md) - 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](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md#background-removed-image-sources).

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`](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md), 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](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md).

### 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](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md#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](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md).

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](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md).

### A variable's binding is read-only

The variable is bound to a [custom metadata](https://docs.scaleflex.com/developers-headless/studio/template-builder/custom-metadata.md) 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.
