Troubleshootingtroubleshooting

Troubleshooting

Debug the version, runtime, remote sync, and cursor persistence issues that show up most often in the current integration flow.

Version driftServerless runtimeCursor persistence

Common failure modes

Most integration failures now cluster around version mismatch, runtime mismatch, or missing persistence on request-scoped hosts.

If generated imports or commands do not match the docs, run `npx clivly --version` — an older installed version is the usual cause.
If sync stops after the first serverless request, move from `start()` to `runScheduled()` or `createClivlyHandler()`.
If every cold start re-reads the entire dataset, add a persistent `cursorStore`.
If remote sync stops after rotating secrets, redeploy the host with the new `CLIVLY_SYNC_TRIGGER_SECRET`.
If the widget 403s, check `allowedOrigins` — it is exact-match, so `https://example.com` does not cover `https://www.example.com`.
If the browser bundle throws on `node:fs` or `node:child_process`, something imported the `clivly` package root instead of `clivly/sdk`.

Persist the cursor on request-scoped hosts

Serverless and edge runtimes need persisted cursors so delta sync survives cold starts.

clivly.config.ts

const clivly = createClivlySDK({
  apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY!,
  entities,
  source: { /* ... */ },
  cursorStore: {
    get: async (entity) => {
      const raw = await kv.get(`clivly:cursor:${entity}`);
      return raw ? { id: raw.id, time: new Date(raw.time) } : null;
    },
    set: (entity, cursor) =>
      kv.put(`clivly:cursor:${entity}`, cursor && {
        id: cursor.id,
        time: cursor.time.toISOString(),
      }),
  },
});

Fast debug checklist

These checks are the fastest recovery path before diving into package internals.

Confirm `CLIVLY_SECRET_KEY`Run `npx clivly status`Run `npx clivly doctor`Verify route path and secretPersist cursors on serverless

Stability

Open Section

End of the docs flow

The remaining references are linked from the overview page.

Clivly docs that match the product you ship today

Troubleshooting