Common errors

Nothing appears at all. In the browser console, check:

• The <div> has both data-site and data-thread.
• The <script> points at a real version (e.g. 0.5.4).
• data-api points at your API.
• In a SPA, the widget auto-mounts any [data-thread] element added after the initial script load (Next.js / Astro / SvelteKit soft-nav, bfcache restore) — no manual re-mount needed.

“Couldn’t load comments” / an error box. Almost always origin mismatch. The browser’s console will show a CORS error on the API call — that means the page’s address-bar origin is not the origin you registered. Fix by re-registering the site at the form, or editing the existing site to the correct origin. A few real-world traps:

• Trailing slash on the registered origin. It used to silently fail CORS — the API now strips slashes for you on register and edit, so this is mostly a problem with old sites registered before the fix.
• www. vs. bare host — https://www.yourblog.com and https://yourblog.com are different origins. Pick the one your pages actually serve from.
• A path in the origin — origins don’t include paths. The same registered origin covers /blog/*, /about, everything.
• file://… (opening an HTML file locally) has no origin and is always rejected — serve over http://localhost instead.

403 on POST but the GET works. Same root cause: the CORS preflight posting /v1/comments needs the same origin match as GET /v1/comments/:threadId. Fix the registered origin and both go green.

Unknown key. data-site doesn’t match a registered site — likely a copy/paste into the wrong site, or the site was deleted. Re-check your dashboard’s public key.

My new comment doesn’t show up. Expected — new comments are held for moderation until you approve them. Head to the dashboard Review queue.

Comments disappeared after I edited the page. You probably changed data-thread. Comments are tied to that exact string; put the old value back. (This is why a stable id beats a slug — slugs change when you rename posts.)

All comments on every page collapsed into one thread. Two pages are sharing the same data-thread. Give every page its own id. If your CMS only gives you a slug and your site has comments under multiple top-level paths (e.g. /blog/* and /articles/*), namespace the id with a prefix so the two never collide: data-thread="blog-${slug}", data-thread="articles-${slug}".

Comments are visible on the dashboard but not on the page. The data-thread on the page is different from the thread id on the comment. Either the page id changed or you’ve commented from somewhere with a different id — same fix: pick one stable id per logical page and stick with it.

Will Threadly drop JS in my visitors’ browsers? Yes — one script tag, deferred. That’s the whole embed. No tracking pixels, no third-party cookies, no preconnects to ad networks.

Does it work with my CMS? If your CMS lets you paste a <div> and a <script> into a post template, yes — that’s exactly the embed. We don’t ship first-party plugins yet.

Will it slow my page? The widget script is ~10 KB gzipped and defers. We try to keep the API round-trip under 200 ms on warm caches so the rendering feels inline with the rest of your page.