Troubleshooting

The connection doesn't verifyCopy Anchor Link

"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/rootsmith must reach createRootSmithHandler.
• The route is public. Auth middleware, proxy.ts or middleware.ts matchers, basic auth, and deployment protection must let it through.
• No redirect. RootSmith doesn't follow redirects. If your domain redirects, such as from example.com to www.example.com, save the final domain in RootSmith.
• The variables are set on the server, then redeployed. ROOTSMITH_SITE_ID must match the site, and ROOTSMITH_CONNECTION_SECRET must be the current secret.

You can test the route yourself:

A 401 from an unsigned test request is expected and means the route is reachable.

You rotated the secretCopy Anchor Link

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 404Copy Anchor Link

• 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 publishingCopy Anchor Link

• Make sure the refresh handler is deployed and verified.
• If you use a CDN in front of Next.js, purge it in a custom refresh function.
• A lost refresh corrects itself within an hour, when the cache expires.

The page stays "confirmation pending"Copy Anchor Link

The page is public, but RootSmith hasn't found the version marker yet.

• The SDK adds it in RootSmithPage. If you use MarkdownContent, add data-rootsmith-content and data-rootsmith-version to 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 blockedCopy Anchor Link

• A site with a delivery endpoint that isn't connected can't publish. Verify the connection, or clear the endpoint to use another method.
• Changing the site's domain cancels pending publications and needs a new connection check.
• Publishing needs an active plan for the team.