Troubleshooting

Most AscendKit failures include an AK_... error code and a request ID. Rerun CLI commands with --debug or --verbose before contacting support.

ascendkit doctor --verbose
ascendkit set-env pk_dev_your_public_key --debug

Redirect loop after login

Use isSessionReady before redirecting. A protected-route guard should wait until the SDK has resolved both the Better Auth session and the AscendKit user profile.

Likely causes:

• redirecting while authStatus is still loading
• treating waitlisted users as normal authenticated users
• missing APP_URL or preview host in allowedHosts

Check:

const { isSessionReady, isAuthenticated, isWaitlisted } = useAscendKit();

Auth component renders blank

Enable SDK debug mode:

<AscendKitProvider debug>{children}</AscendKitProvider>

Likely causes:

• no auth providers configured
• OAuth provider enabled but not ready
• missing NEXT_PUBLIC_ASCENDKIT_ENV_KEY
• component rendered outside <AscendKitProvider>

Waitlisted user appears authenticated

Use the explicit waitlist fields:

const { authStatus, isAuthenticated, isWaitlisted, isRejected } = useAscendKit();

isAuthenticated is only true for users allowed into the app. Use isWaitlisted for pending approval screens and isRejected for rejected-access screens.

Webhook signature verification fails

Check:

• use the raw request body, not parsed JSON
• pass the X-AscendKit-Signature header unchanged
• use the endpoint's whsec_... secret
• reject stale timestamps outside the default five-minute tolerance

The payload uses event as the canonical event field and also includes eventType as a compatibility alias.

Template variable not replaced

Check the variable scope. Journey event properties are not automatically email template variables. Set values with:

ascendkit vars set dashboardUrl https://app.example.com/dashboard

Then reference them as {{dashboardUrl}}.

CLI command exits but config did not change

Run:

ascendkit doctor --verbose
ascendkit status

Then rerun the command with --debug. Confirm the active project, environment, API URL, request ID, and any AK_... error code in the output.