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 discard memory between invocations, so without a persisted cursor every delta sync starts from nothing and re-reads your entire source tables — a full sync on every run, reported as a success. Use the store the SDK ships:

clivly.config.ts

import { createClivlySDK, kvCursorStore } from "@clivly/sdk";

const clivly = createClivlySDK({
apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY!,
entities,
source: { /* ... */ },
cursorStore: kvCursorStore(env.CLIVLY_CURSORS),
});

The SDK warns at startup when it detects a serverless runtime without one, clivly status flags it, and Clivly's dashboard warns when your scheduled syncs keep re-reading everything. See Cursor stores for writing your own, including the Date round-trip trap.

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 → sync cursor persists → boot hook wired → setup checks → dashboard-authored objects → 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.