Start with the symptom
| What you see | Most likely cause | Go to |
| No launcher on the page | Script blocked, wrong address, or site not allowed | Checks 1 to 4 |
Console shows 403 and origin_not_allowed | The site is not on the allowed-domains list | Check 4 |
| Launcher appears, but only a leave-a-message form | No agent is available, or you are outside business hours | Check 6 |
| Visitors can write, but agents see nothing until they refresh | WebSockets are blocked for the dashboard | Check 7 |
Requests fail with 429 at busy times | A reverse proxy makes all visitors look like one address | Check 8 |
IIS shows 500.19, 500.30 or 502.5 | Hosting Bundle, pool or startup fault | Check 9 |
Check 1. Is the server up?
Open these two addresses on your chat server in a browser:
| Address | Good answer | What a bad answer means |
/api/health | "status": "healthy" | The application is not running, or a proxy cannot reach it |
/api/health/ready | "status": "ready" | A 503 with database: unreachable means the server cannot reach SQL Server. Check the connection string in appsettings.json |
If both are fine, the server is working and the fault is between it and your page.
Check 2. Does the script load?
On the page with the problem, open the browser's developer tools (F12), choose the Network tab, reload, and filter for dchat. You are looking for /widget/dchat.iife.js with status 200.
- Nothing listed: the snippet is not on this page. View the page source and search for
dchat.iife.js. A page cache or CDN may still be serving an old copy, so clear it.
- 404: the address in
src is wrong, or the site's root is not the Web folder.
- Blocked or cancelled: try a private window with extensions turned off. A privacy extension can block chat scripts for that one browser while everyone else sees the widget.
Also confirm that data-server-url is on the tag and holds the full server address. The widget does not start without it.
Check 3. Is HTTPS consistent?
A browser refuses to load an http:// script on an https:// page and reports Mixed Content in the console. Serve the chat server over HTTPS with a valid certificate, and use https:// in both src and data-server-url. An expired or self-signed certificate fails the same way, so open the script's address directly and see whether the browser warns you.
Check 4. Is this site allowed?
If you have listed allowed domains, the server refuses every other site. The console shows a 403 response with the code origin_not_allowed, and the widget stays hidden.
Open Widget Builder > Allowed domains and add the site. Remember that *.example.com covers subdomains but not example.com itself, so list both if you use both. Staging sites and a new domain are the usual things people forget.
Check 5. Is your site's security policy blocking it?
A Refused to load or Refused to connect message in the console that mentions Content Security Policy means your own site blocked the widget. Add your chat server to script-src and connect-src, and to img-src and media-src for attachments. The widget adds a style element to its shadow root, so check style-src too.
Check 6. The widget shows only an offline form
That is the widget working as designed: nobody is available to chat. Check these in order:
- An agent has the dashboard or desktop app open, and their status is online. An agent who has chosen to appear offline does not count.
- The current time is inside your operating hours. Outside them the widget is offline even when an agent is signed in.
- At least one online agent is below the concurrent-chat limit. When everyone is full, the widget stops offering live chat.
- The agent's connection is working. If the dashboard keeps disconnecting, see check 7.
To test, sign in to the dashboard in one browser and open your site in a private window in another. The widget checks agent status regularly, so give it a few seconds to change.
Check 7. Agents do not get messages in real time
Visitors and agents connect differently. The visitor widget uses ordinary HTTP requests, while the dashboard and desktop app keep a live connection to /hubs/chat over SignalR. That is why visitors can appear to work perfectly while agents get delayed messages or repeated disconnects. The browser console on the dashboard shows WebSocket connection failed.
On Nginx, pass the upgrade headers:
location / {
proxy_pass http://127.0.0.1:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
On IIS, install the WebSocket Protocol role service under Web Server > Application Development in Server Manager, then restart IIS.
Behind a load balancer, firewall or CDN, confirm that it allows WebSockets and that its idle timeout does not cut long-lived connections.
Check 8. Errors with status 429 at busy times
The server limits how many requests one visitor address can make. Behind a reverse proxy, DChat sees the proxy's address unless you say the proxy can be trusted, so every visitor can look like the same person and share one limit.
List your proxy in appsettings.json. DChat then reads the real address from X-Forwarded-For, for that proxy only:
{
"Network": {
"TrustedProxies": [ "127.0.0.1" ]
}
}
Use your proxy's real address, or Network:TrustedProxyNetworks for a range. Do not list addresses you do not control, because a trusted sender can claim to be any visitor. The same setting makes IP blocks apply to the real visitor.
Check 9. IIS error pages
| Error | Usual cause | Fix |
500.19 | IIS does not recognise the ASP.NET Core module | Install the ASP.NET Core Hosting Bundle for .NET 8 after the IIS role, then restart IIS |
502.5 or 500.30 | The application failed to start | Read the log described below. A bad connection string or a missing runtime is the usual reason |
503 | The application pool has stopped | Start the pool, and confirm its .NET CLR version is No Managed Code |
Read the server log
When the cause is still unclear, the log usually says it plainly. DChat writes daily files to Web\App_Data\logs\ and keeps them for 31 days. Reproduce the fault, open the newest file, and search for ERR or the time of your test. With Docker, use docker logs on the container. On Linux with systemd, use journalctl -u with the name of your service.
Remove passwords and personal details before you share a log with anyone.
Common questions
Why is my live chat widget not showing?
The usual causes are a snippet missing from the page, a wrong server address, an http script on an https page, or a site that is not on the allowed-domains list. The browser console and Network tab show which one applies.
Why does the widget say we are offline when an agent is signed in?
Being signed in is not the same as being available. An agent must have the dashboard or desktop app open with an online status and be below the concurrent-chat limit, and the time must be inside your operating hours.
Does the DChat widget need WebSockets?
No. The visitor widget uses ordinary HTTP requests. The dashboard and desktop app use a live SignalR connection, so turn WebSockets on in your proxy or IIS for agents to get messages in real time.
What does origin_not_allowed mean?
Your chat server has an allowed-domains list and the site showing the widget is not on it. Add the site under Widget Builder, Allowed domains.
Where are the DChat server logs?
In the App_Data logs folder inside the Web folder. The server writes daily files and keeps them for 31 days.