GlassKit Docs — Troubleshooting

The per-doc troubleshooting sections cover their own domains. This page is the aggregator: every gotcha across the boilerplate collected so you can search one place. Each entry links back to the originating doc for the full context.

Auth + Convex

Stripe + billing

Pairing + glasses

Deploy + build

Purchase + delivery

Add-on toggling

"When in doubt"

If a symptom doesn't appear above

Fastest path:

Check the Vercel function logs for the failing route
Check the Convex dashboard logs for the failing action / mutation
Check the per-domain doc's Troubleshooting section
Post in the customer channels of our Discord and paste the error message verbatim

Troubleshooting

Auth + Convex

Cannot find module '@glasskit/backend/convex/_generated/api'

Convex queries return undefined

Clerk → Convex: 'Failed to authenticate JWT'

Convex env validation failed at deploy

Stripe + billing

createCheckout throws 'Not authenticated'

Stripe webhook hits Convex but tables don't update

Plan stays 'free' after a successful checkout

'No such price: price_...'

Customer portal returns 404

Pairing + glasses

My Display isn't showing on /pair

Approved on the phone but the glasses didn't sign in

Pairing timed out

'Your account needs extra verification (MFA)'

'[CONVEX M(pairing:mintAndAttach)] CLERK_SECRET_KEY not set'

claimPairingSession throws 'Unauthenticated'

Deploy + build

Checkout returns 500 right after clicking 'Get GlassKit'

pnpm-lock.yaml conflicts when merging upstream

CI build crashes with 'Cannot read properties of undefined' on import.meta.env

Next.js 'Event handlers cannot be passed to Client Component props'

Purchase + delivery

'I just bought but no GitHub invite arrived'

'I joined Discord but I'm not in the paid channels'

Add-on toggling

`pnpm run addon enable <id>` throws 'verifyFenceMarkers: missing fence …'

`pnpm exec convex env set` failed with 'not authenticated'

"When in doubt"

On this page