Troubleshooting

If your issue isn't here, check the Vercel build log or browser console — the actual error message is usually specific enough to fix.

Install / build errors

`pnpm: command not found`

You don't have pnpm installed globally.

npm install -g pnpm

`Module not found: Can't resolve '...'`

Your node_modules is stale.

rm -rf node_modules pnpm-lock.yaml
pnpm install

Build out-of-memory (FATAL ERROR: Reached heap limit)

The project already allocates 4 GB in package.json. If it still OOMs:

Close other apps / tabs
Disable @next/bundle-analyzer (unset ANALYZE)
Upgrade the Vercel plan (Pro has more build memory)

`TypeError: fetch failed` during build

Usually .env.local is missing a variable the build requires.

Check the log for the line above the error — it often names the missing key.

Database / Supabase

`permission denied for table apps` (or similar)

Your RLS policies aren't matching the current user. Quick checks:

Are you using the right Supabase client? Server routes should use getSupabaseAdmin() (service role), client components use getSupabaseClient() (anon key).
Is the user actually logged in? supabase.auth.getUser() returns null?

`invalid input syntax for type uuid: "..."`

You passed a non-UUID string where the schema expects uuid. Usually happens when mixing slugs with IDs.

"Connection refused" from `pnpm db:test`

Check NEXT_PUBLIC_SUPABASE_URL is set (no trailing slash)
Check SUPABASE_SERVICE_ROLE_KEY is the long eyJ… value, not the anon key
Try the URL in a browser — if it 404s, the project URL is wrong

Auth

You forgot to:

Update NEXT_PUBLIC_APP_URL on Vercel → redeploy
Add your production URL to Supabase → Authentication → URL Configuration → Redirect URLs

Google's OAuth client doesn't know about your callback URL. In Google Cloud Console → your OAuth client → Authorized redirect URIs, add the Supabase callback URL (shown on the Supabase Google provider page, usually https://xxx.supabase.co/auth/v1/callback).

Admin pages show "404" or "Forbidden" even though I set `is_admin`

The project checks both is_admin and role. Make sure both are set:

update users set is_admin = true, role = 'admin' where email = 'you@example.com';

Stripe

Webhook returns 400 "No signatures found matching the expected signature"

The STRIPE_WEBHOOK_SECRET doesn't match the one Stripe uses.

Local dev: use the secret printed by stripe listen, not the dashboard one
Production: copy the secret from the specific webhook endpoint, not from the API keys page

Webhook returns 200 but the order isn't marked paid

Check the webhook handler code path in app/api/webhooks/stripe/route.ts. The event type may not be in the list of handled events. Add it or check that Stripe is emitting the event you expect.

"Stripe products aren't showing on /pricing"

Make sure:

STRIPE_PRICE_ID_PREMIUM (and any other Price IDs you reference) are set
config/payments.config.ts has provider: 'stripe'

Cron jobs

Cron returns 401

CRON_SECRET is missing or wrong. Double-check:

Set in Vercel Settings → Environment Variables
Redeployed after setting it (Vercel doesn't apply env changes until redeploy)

Verify your domain in Resend
Set RESEND_PRODUCTION_FROM to an email at your verified domain
SPF + DKIM records from Resend should all show green

images: {
  remotePatterns: [
    // ...
    { protocol: 'https', hostname: 'yourproject.supabase.co' },
  ],
}

Redeploy.

Still stuck?

Double-check .env.local against .env.example — missing a var is the #1 cause
Search the exact error message on GitHub Issues / Stack Overflow
Ask in our Discord (link in site.config.ts) or open a GitHub issue

Debug with AI

AI Prompt· Debug this error

I'm hitting this error in my DirectoryKit project:
\{paste the full error message, including the stack trace if any\}
When it happens: {e.g. "on pnpm build", "when I visit /pricing", "on sign-in", "on Stripe webhook"}
What I tried: {what you've already attempted}
Recently changed: {files I edited right before the error started, or "nothing — it worked yesterday"}
Please:

Explain what this error means in plain English.
Read the relevant files in the project (config/, lib/, .env.example) and diagnose the likely root cause.
Give me the exact fix — file path, before/after snippet, or env var to set.
If it's a classic gotcha (missing env var, RLS policy, Stripe webhook secret mismatch, pnpm-vs-npm), tell me so I know what to watch for next time.
Don't guess — if you need to see a file, tell me which one before suggesting a fix.