Troubleshooting
Embeds
A blank space where the demo should be, and every other embed problem.
When an embed cannot load, it does not show an error on your website. It collapses to nothing on purpose, so a broken embed never puts our wording on your client's page. That makes problems easy to miss. This page walks through every cause.
Check the embed card first
Open Developers → Embeds and find the embed. The card tells you most of what you need:
| Badge or warning | Meaning | Fix |
|---|---|---|
| No domains yet | New embeds allow no websites at all. | Add the website's domain under Allowed domains and press Save. |
| Switched off | The Live box is unticked. | Tick Live and press Save. |
| This embed is installed somewhere it is not allowed. | It is on a website that is not in Allowed domains. The card lists the blocked domains with attempt counts. | Add the one you recognize to Allowed domains. |
| Some pages were refused. | It works on some sites and is blocked on others. | Same: add the domain from the blocked list. |
| Live | The embed is allowed to load. | If it still does not show, keep reading. |
The embed is blank or missing
Work down this list. The first four cover almost every case.
1. The exact domain is not allowed
Allowed domains are strict:
www.example.comandexample.comare different. List both if your site answers on both.*.example.comdoes not coverexample.com. List both if you need both.- A bare domain means
https://. If the page is served over plainhttp://, typehttp://in front. - A port is part of the domain.
localhost:3000is its own entry. - You can list up to 8 domains.
After you save a new domain, give it about a minute. The allowed list is cached briefly.
2. The site builder changes on every deploy
Preview links from Vercel, Netlify, Lovable, and similar tools often change on every deploy. You can either list the stable production domain and test there, or use Allow any domain for the embed.
3. The snippet was changed or only half pasted
For an inline embed you need both parts: the <div data-lumina-embed=...> where the demo should appear, and the <script src=".../embed.js" async> after it. For a bubble you need the one <script> tag, once, in the page head or before </body>.
- Do not change any
data-lumina-...attribute. - Copy the snippet again from the embed's Snippet tab if in doubt.
- If you pressed Rotate key, every old snippet stopped working. Paste the new one.
4. Your account cannot run live demos right now
Embeds go blank when your plan is not active, when the account is suspended, or when the embed was deleted. Check Billing. See Billing and usage.
5. The page hides it
A parent element with a fixed height or overflow: hidden can cut the embed off or hide it completely. The inline embed resizes itself, so its container must be free to grow. A sandbox attribute on an iframe also blocks it.
6. The site builder strips scripts
Some editors remove <script> tags:
- WordPress: use a Custom HTML block for an inline embed. For a bubble, use your theme footer or a header and footer scripts plugin. The classic editor's text fields strip scripts.
- Webflow: use an Embed element for inline. For a bubble, use Project Settings → Custom Code → Footer Code. Custom code only runs on the published site, not in the designer.
- Squarespace: use a Code Block (business plans and above). On lower plans, use the Plain iframe tab instead.
- Shopify: use a Custom Liquid section for inline, or put the bubble script in
theme.liquidbefore</body>.
If the builder cannot run scripts at all, use the Plain iframe tab. It has a fixed height and no auto-resize, and a bubble cannot be done this way.
7. A single-page app loaded the page after the script ran
In React, Next.js, Vue, and similar apps, a container added after the first page load is not found automatically. Call window.LuminaEmbed?.refresh() after the route renders. See the Embed JavaScript API.
"This demo has to be embedded"
You opened the embed's own address in a browser tab. Embeds only run inside a page on an allowed domain. Open the website the embed is installed on instead.
The demo shows, but calls or chat do not work
| What happens | Cause | Fix |
|---|---|---|
| The call connects but nobody hears anything | A hand-made iframe without allow="microphone". | Use the generated snippet, or add allow="microphone" to the iframe. |
| Live call paused / Chat paused | A budget ran out: your monthly plan, the demo's own limit, or the embed's Voice minutes / Chat messages budget. | Buy more on Usage, or raise the embed's budget. |
| You have used today's calls on this demo. | The visitor hit Calls per visitor/day (default 2). | Resets tomorrow, or raise it. |
| You have reached today's message limit on this demo. | The visitor hit Messages per visitor/day (default 20). | Resets tomorrow, or raise it. |
| Could not start the call | The browser blocked the microphone. | See Demos and voice calls. |
The bubble will not save
- The receptionist-and-chat demo is two nodes, and a bubble holds one. Use Inline, or pick a saved demo with exactly one interactive node.
- A bubble needs one interactive node to launch. The demo you picked has none. Add a receptionist, chat agent, or assistant to it.
Other messages
| Message | Fix |
|---|---|
| Your plan includes 3 embeds and all of them are in use. | Delete an embed, or point an existing one at a different demo. |
| You need manage access to demos to change embeds. | Ask your agency owner for manage access to Demos & landers. |
| Use the "allow any domain" switch instead of "*". | * is not a domain. Use the switch, or list real domains. |
| "x" is not a domain we can use. | Type just the domain, like example.com. |
| ... would cover every site under .com. | Wildcards on a whole ending like *.com are not allowed. Name your own domain. |
Let AI find it
For how to install an embed from scratch, see Put a demo on a website and the developer install guide.
Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.
