Troubleshooting
Fix common connection, publishing, and live-check problems with the RootSmith SDK, deploy hooks, and webhooks.
The connection doesn't verify
"We couldn't verify the SDK connection" means RootSmith couldn't get a signed answer from your delivery endpoint. Check each item:
- The site is deployed with the latest code and at the primary domain saved in RootSmith, over HTTPS.
- The route exists.
POST https://<your domain>/api/rootsmithmust reachcreateRootSmithHandler. - The route is public. Auth middleware,
proxy.tsormiddleware.tsmatchers, basic auth, and deployment protection must let it through. - No redirect. RootSmith doesn't follow redirects. If your domain
redirects, such as from
example.comtowww.example.com, save the final domain in RootSmith. - The variables are set on the server, then redeployed.
ROOTSMITH_SITE_IDmust match the site, andROOTSMITH_CONNECTION_SECRETmust be the current secret.
You can test the route yourself:
| Response | Meaning |
|---|---|
503 | ROOTSMITH_SITE_ID or ROOTSMITH_CONNECTION_SECRET isn't set. |
401 | The signature failed. The secret is wrong or old, or the clock is off by more than 60 seconds. |
403 | ROOTSMITH_SITE_ID is for another site. |
404 | The route isn't deployed at that path. |
405 | The route doesn't export POST. |
A 401 from an unsigned test request is expected and means the route is
reachable.
You rotated the secret
Rotating creates a new secret, marks the connection unverified, and cancels
anything waiting to publish. Copy the new secret to
ROOTSMITH_CONNECTION_SECRET, redeploy, then select Verify connection.
Schedule cancelled pages again.
A page shows 404
- The page must be published. Drafts and approved pages aren't public.
- The path must match exactly. Paths have no trailing slash.
- If another route in your app matches the path first, it wins. Check for
overlapping routes, such as
app/blog/[slug].
The page doesn't update after publishing
- Make sure the refresh handler is deployed and verified.
- If you use a CDN in front of Next.js, purge it in a custom
refreshfunction. - A lost refresh corrects itself within an hour, when the cache expires.
The page stays "confirmation pending"
The page is public, but RootSmith hasn't found the version marker yet.
- The SDK adds it in
RootSmithPage. If you useMarkdownContent, adddata-rootsmith-contentanddata-rootsmith-versionto a wrapper. - A webhook receiver must render the marker. See version markers.
- The page must render the marker in its HTML without client-side JavaScript.
RootSmith keeps checking every five minutes for 24 hours. You can also confirm the page by hand.
Publishing is blocked
- A site with a delivery endpoint that isn't connected can't publish. Verify the connection, or choose another way under How is your site built?.
- Changing the site's domain cancels pending publications and needs a new connection check.
- Publishing needs an active plan for the team.
MDX export
Download each published page as an MDX file with front matter and a version marker, then add it to your site yourself.
Set up with an agent
Give your AI agent one prompt and it sets up RootSmith with you, from your brand profile to your first page and your site connection. This page is the step-by-step guide the agent follows.