Troubleshooting

Solve common KilatKoding issues with a diagnosis checklist that points directly to the likely source of the problem.

Start with these two checks

Before you debug further, run:

npm run env:check

and inspect:

GET /api/health

Those two checks are usually enough to tell you whether the issue comes from env config, feature toggles, or database connectivity.

Common issues

Auth pages or the dashboard do not work

Check NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY.

If the auth page now shows a configuration notice, it usually means auth is intentionally disabled by toggle or the Supabase public env is incomplete.

After editing .env or .env.local, restart npm run dev and then run npm run env:check again.

If auth is intentionally not part of the product yet, set:

NEXT_PUBLIC_ENABLE_AUTH=false

Billing or admin always shows a fallback state

This usually means SUPABASE_SERVICE_ROLE_KEY is missing. Billing, webhooks, signed avatar URLs, audit logs, admin reporting, and persistent rate limits all depend on it.

Checkout fails while creating a payment

Check:

• NEXT_PUBLIC_ENABLE_PAYMENTS
• PAYMENT_PROVIDER
• your Midtrans or Doku credentials
• the payments and subscriptions migrations

The payment succeeds at the gateway but the subscription never activates

This usually means the webhook never arrived, the webhook URL is wrong, or signature verification failed. Check the correct webhook route and confirm the production domain is set correctly.

The contact form does not send email

Check RESEND_API_KEY, EMAIL_FROM, and optionally CONTACT_EMAIL. Make sure the sender domain is verified in Resend.

AI routes return 503 or 429

503 usually means the provider is not configured. 429 usually means a usage limit or request rate limit has been reached.

Admin access does not appear

Make sure the user exists in user_roles with the admin role. ADMIN_EMAILS only helps with the initial bootstrap.

Playwright fails the first time you run it

Install the browser first:

npx playwright install chromium

AI prompt you can use right away

Help me diagnose this KilatKoding issue:

Symptoms:
[describe the error, failing endpoint, or incorrect behavior]

Context:
- Environment: [local / staging / production]
- Active features: [describe the active toggles]
- Payment provider: [midtrans / doku / not used]
- AI provider: [openai / anthropic / not used]
- Recent changes: [describe what you changed]

Please give me:
1. The 3 to 5 most likely root-cause hypotheses
2. The fastest inspection order
3. Which files, env vars, tables, or routes I should inspect
4. How to separate the main root cause from side symptoms
5. The safest fix path

Fast diagnosis checklist

Symptom	First thing to check
Many features show disabled or fallback states	.env, .env.local, restart the dev server, then npm run env:check
Login redirects behave strangely	Supabase redirect URLs and auth callback configuration
Admin data is empty	Service role env and admin role assignment
Payments never finalize	Webhook URL and signature verification
Avatar uploads fail	Storage migration and service role env
Contact form fails	Resend key and verified sender domain

When to check the database directly

Look at the database directly if the issue involves:

• user roles,
• subscription status,
• payment records,
• audit trail,
• webhook event logs.

The most likely tables to inspect are user_roles, subscriptions, payments, audit_logs, and webhook_events.

When to inspect code

Go into the code if:

• env values look correct but the behavior is still wrong,
• you recently changed config/*,
• you edited a route handler or dashboard component,
• you added a new integration on top of the existing patterns.

If you are doing a large rebrand, some issues that look like bugs are really just copy, navigation, or feature-toggle mismatches that have not been aligned yet.