Troubleshooting

Using Linktrap in the browser

• Cannot sign in or session drops: allow cookies for your site; in Clerk, production URLs and redirects must match where the app is hosted. Try another browser or disable extensions that block auth.
• “Quota” or cannot create more links: free workspaces have a monthly limit — see 403 monthly quota below or upgrade from the dashboard.
• Preview card looks wrong: see Crawler checklist and How your links work.

Build fails (Clerk)

Set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY for production builds. Placeholder values may work locally but should not ship.

503 / database errors

• Confirm TURSO_DATABASE_URL (and token if remote) on the server.
• Ensure schema is pushed: npm run build runs db:push when TURSO_DATABASE_URL is set at build time, or run npm run db:push manually — missing tables cause API errors.

401 on /api/links or generate-meta

User must be signed in. Cookie blocked (third-party context, wrong domain) breaks session — align site URL with Clerk settings.

403 monthly quota

Free workspaces have a per-calendar-month link creation cap. Upgrade to Pro or wait for the next month UTC boundary.

Preview shows wrong card / real URL

• Social caches: use each network's debugger and allow time for refresh.
• If a crawler is not in lib/crawler-uas.ts, it may get the human interstitial or behave unexpectedly — extend UA list carefully.
• Never put destination URL in botDescription. See Crawler checklist.

Stripe webhook not updating plan

• Verify signing secret matches the endpoint in Stripe Dashboard.
• Ensure checkout.session.completed includes metadata.workspaceId or subscription linkage can be resolved.
• Check idempotency: duplicate event ids are ignored — intentional.

Custom domain not rewriting

• verified must be true in custom_domains.
• Host header must match stored hostname (no port mismatch on local tests).
• Path must be a single segment (e.g. /promo), not /s/promo on the custom host (that path is reserved for the default app routes if exposed).

Go-live checklist

1. POST /api/links requires authentication (not public).
2. Production database schema synced (build-time db:push or manual push).
3. Stripe webhook tested (CLI or dashboard replay).
4. Terms, Privacy, Acceptable use linked from the product.
5. Quota and error copy reviewed for your audience.