My widget is not showing up
Check four things in order: the agent is published, the browser origin exactly matches the allowed domain, the snippet is really in the page source, and the Chat toggle in the widget studio is on.
Last checked against the running product on 30 August 2026.
Two symptoms, and they point at different halves of this list. If no launcher appears at all, the widget never mounted: look at steps 1, 3, 4 and 6. If the launcher appears but the panel says the assistant is unavailable, the widget mounted and the server refused it: look at steps 2, 5 and 7.
Confirm the agent is published
Open Agents and read the badge on the agent. Only an agent whose status is exactly published is served. A draft is not, and neither is a paused agent — every widget entry point checks the same status, so there is no partial state where some of it works.
Publish the draft, or choose Resume agent on a paused one, then reload your site.
Compare the origin with the allowed domain, character for character
Read your browser's address bar, then read Allowed website domain in the agent editor's Appearance section. Garuda matches the origin the browser reports against that value exactly.
Origin mismatches that silently refuse the widget What you see What is wrong Address bar shows www., allowlist has the bare domain Two different origins. Approve the one your site actually serves. Testing on a staging or preview hostname A different hostname is a different origin. It is not covered. The page was opened as a file on your computer A local file sends no origin, and a request with no origin is refused. The allowlist is empty Saving the editor with the field blank clears it. Put the hostname back and save. Wildcards do not work
There is no subdomain matching and no pattern syntax. shop.example.com and example.com are separate values, and the editor holds one at a time.
Prove the snippet is really on the page
Not in your site builder — in the page the browser received. Open the page, view source or open developer tools, and search the markup for
data-agent-key.- Not there at all: the builder stripped the script, or the code block only renders on one page or one template. Many builders refuse script tags in ordinary rich-text blocks — use the site-wide custom code or footer field instead.
- There, but the key is wrong or truncated: copy it again from Widget, Install. An invalid key makes the widget stop before it draws anything, and it does so without writing to the console.
- There, and the tag has picked up a
data-garuda-loadedattribute: the script ran. Move on to the next step.
Check the Chat toggle
Open Widget, the Customize tab, section 5. Chat is on by default, and turning it off hides the entire widget — launcher included — because typing is the only conversation this widget offers. It is the most easily missed cause of a launcher that has vanished with no error anywhere.
While you are there, check the Widget position in section 4 matches the corner you have been looking at.
Read the network requests
Open developer tools, go to the Network tab and reload the page. Three requests matter, and their responses name the problem precisely:
Widget network requests and what a failure means Request What a failure tells you widget.js Blocked or not requested at all means the snippet is missing, or a content blocker or a Content-Security-Policy on your site is stopping it. Allow the API host in your script-src and connect-src. The agent lookup A 404 saying the published agent was not found covers both causes deliberately: the agent is not published, or this origin is not on its allowlist. Go back to steps 1 and 2. The session request 402 means the workspace has no active subscription. 429 means it has reached its rolling 30-day conversation allowance of 100. The console is often empty, and that is expected
A widget with an invalid configuration fails closed on purpose and writes nothing to the console, so that a misconfigured embed cannot leak identifiers into a stranger's browser. An empty console is not evidence that the snippet is fine — the Network tab is where the answer is.
Look for something on top of it
A cookie banner, a sticky footer or a chat bar from another vendor can cover the launcher completely. The widget defaults to a very high stacking order, but you can raise or lower it with
data-z-indexon the script tag; the value is clamped between 1,000 and 2,147,483,000.Rule out caching and the browser itself
The widget script is cacheable for five minutes, and your own site or CDN may cache the page for much longer. Hard-refresh, then try a private window and a second browser. A tracking blocker or a strict privacy extension will also stop the script.
One more check that is worth doing early with several agents: the key in your snippet has to belong to the agent you have been editing. The Widget screen shows the first live agent it finds, so it is easy to install one agent and then spend an afternoon configuring another.
If it still does not work
It works on your computer but not on a colleague's
That points at their browser rather than your setup: an ad or tracker blocker, a corporate proxy, or an extension stopping third-party scripts. Ask them to try a private window with extensions disabled.
Two launchers appear
The snippet is on the page twice with two different keys. One key per page: Garuda already prevents the same key mounting twice, including on single-page-application navigations.
The panel opens but replies never come
That is not an installation problem. Check the agent answers in the Conversation playground on its own page; if it fails there too, the problem is in the agent rather than the embed.
You have worked through all of it and it still does not appear
Write to info@ravan.ai with the page URL, the agent name, and the status codes you saw in the Network tab. Those three make it diagnosable in one reply.
Related articles
- Getting startedInstalling the widget on your websiteCopy the one-line script from Widget, Install and paste it before the closing body tag on every page that should show the chat. Step-by-step guides for Webflow, WordPress, Shopify and Framer are on the same tab.
- Getting startedApproving the domains your agent may run onThe allowed domain is set in the agent editor, under Appearance. Garuda compares it to the browser origin exactly, with no wildcards and no automatic subdomain matching.
- OperatingPausing or unpublishing an agentPause takes a published agent off the air from its detail page and keeps every setting; resuming is one click back. Unpublishing to Draft has no button in the portal yet.