Troubleshooting

The widget doesn't appear

• Open DevTools → Network and confirm embed.js loaded with HTTP 200. A 404 means the script URL is wrong; double-check the release path.
• Confirm the script tag has data-assistant-id set. Without it the script loads but never auto-injects an element.
• Inspect the DOM and search for <zupport-chat>. If it exists but is invisible, your site CSS may be hiding the launcher — try bumping --zupport-z-index.
• Check the console for an zupport-error with phase config — see “Config 404 / 403” below.

Config 404 or 403

The embed could not load config.json. Causes:

• The assistant ID is wrong. Copy it again from the Embed tab.
• The assistant was deleted. Its CDN files are gone — create a new assistant.
• You're using a custom data-config-base-url that doesn't follow Zupport.chat's bucket layout. The URL the embed fetches is {baseUrl}/assistants/{id}/config.json.

Model download stalls

• First load on a slow connection can take a minute or two — the Qwen3 model is ~570 MB. Check Network for in-flight requests before assuming it's stuck.
• Corporate proxies sometimes block Hugging Face Hub. Self-host the weights and point at them with data-model-base-url.
• Try forcing a fresh download to rule out a corrupted cache: data-disable-cache="true".

Wrong runtime engaged

Listen for zupport-tier-change and check e.detail.reason. Common cases:

• engine-init-failed — WebGPU rejected the model (often a driver issue on Linux) and the widget downgraded to scenarios. To force scenarios explicitly for QA, set data-engine-override="scenarios".
• Mobile device picked the scenarios engine — that's expected. Browser support explains which devices land where.

CSS conflicts

Shadow DOM prevents your site CSS from leaking into the widget, but the launcher itself is positioned with position: fixed on the host element. If a site-wide rule hides fixed elements (e.g. position: fixed { z-index: 0 }), it can collide.

• Bump --zupport-z-index on zupport-chat.
• Avoid setting overflow: hidden on body globally.

iOS shows “I don't have an answer for that yet”

iOS runs the scenarios engine — no LLM. If no scenario matches the visitor's question, the widget falls back to the message you set in Configure → Scenario fallback message. To cover more cases on iOS, write more scenarios (and remember to publish them).

Stuck on “Building…” after Publish

The build pipeline failed silently and the UI didn't catch up. Refresh the sources tab; if the status is still processing after a minute, delete and re-upload the source. We've shipped defensive fixes for this on the assistant overview and switcher cards, so most cases self-resolve now.

Events never fire

• Listeners must be attached after the element exists. With CDN auto-inject the element is created on DOMContentLoaded — attach listeners later than that, or query the element after waiting one tick.
• Listeners on document work because events bubble and are composed. Listeners on inside the Shadow DOM won't reach you — keep them on the host element or above.