Troubleshooting

Diagnostics

Persist cursors on request-scoped hosts, and use the fast debug checklist and status ladder to recover quickly.

Where to start

Most integration failures cluster around version mismatch, runtime mismatch, or missing persistence on request-scoped hosts. See Common errors for the full symptom list.

Version mismatch

Do the installed package and the workspace agree?

Errors mentioning unknown fields, or a schema the server rejects.

Runtime mismatch

Is the host long-lived or request-scoped?

Sync works locally and stalls on serverless — usually an unpersisted cursor.

Missing wiring

Does an active mapping accept these rows?

Every local check passes and the workspace still stores nothing.

`clivly status` names the family for you — read it before the table below.

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 secret
Persist cursors on serverless

Reading the status ladder

npx clivly status runs the whole ladder and tells you which step you are on: credential → Clivly reachable → config loads → config is edge-safe → setup checks → sync trigger URL. See CLI commands for the full command reference and the deprecated single-step aliases.

Terminal

Sync trigger URL
! Still the placeholder (https://<yourDomain.com>/api/clivly/tick)
  — remote sync cannot call back into this app.
  Replace <yourDomain.com> with your deployed origin, or delete the
  line. For local development run `clivly dev`.

A warning here is not a failure. Push-only deployments — where your app decides when to sync and nothing needs to call in — can leave this unset permanently. See Environment variables and How Clivly reaches your app for how the trigger URL resolves.