# Troubleshooting

> Fix common connection, publishing, and live-check problems with the RootSmith SDK, deploy hooks, and webhooks.

Source: https://docs.rootsmith.io/docs/publishing/troubleshooting.md

## 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/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:

| 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 `refresh`
  function.
- 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 use `MarkdownContent`, add
  `data-rootsmith-content` and `data-rootsmith-version` to a wrapper.
- A webhook receiver must render the marker. See
  [version markers](https://docs.rootsmith.io/docs/publishing/webhooks.md#show-the-version-marker).
- 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 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.