Troubleshooting

Find your symptom below. Where a command printed an error, the quoted message helps you match it. When you ask for help, share the command and the error text, but never your .env or a full provider response.

Find your symptom

Getting the starter

Invitation and clone problems

If Starter kit still says Invitation sent, check that GitHub is signed in to the same account shown on the card, then choose Accept invitation from the dashboard. If the invitation expired, choose Resend invitation. Accepting from a different GitHub account won't give you access.

If git clone says Repository not found or asks for a password, Git on your computer isn't signed in to the GitHub account that has access. The starter is private, so GitHub hides it from other accounts. Sign in one of these ways, then clone again:

• On Windows, Git's credential manager usually opens a browser sign-in the first time you clone. Choose the connected GitHub account.
• With GitHub CLI, run gh auth login and follow the prompts.
• Use GitHub Desktop, signed in with the connected account.

Don't put an access token in the clone URL. See Setup for the full access flow.

Local setup

npm is blocked in PowerShell

If PowerShell reports that running scripts is disabled for npm.ps1, Windows is blocking npm's PowerShell wrapper. Use npm.cmd instead of npm in the same commands, such as npm.cmd ci, or open a Command Prompt terminal in your editor. Microsoft's execution policy guide explains how to change the setting if you prefer.

Environment variables are not loading

Confirm the terminal is in the project folder containing package.json, .env.example and scripts/kickstart/. Kickstart and the app read the root .env. A file inside app/, a file named .env.txt or a conflicting .env.local can make the installer and development server see different settings.

1. Check the file name and location in your editor without printing its values. On Windows, turn on file name extensions in File Explorer to spot .env.txt.
2. Edit the existing line once. If a setting appears twice, decide which value belongs to this installation and remove the other.
3. Restart the development server. A deployed app needs a new deployment to pick up changes.
4. Run the read-only npm run kickstart:check to separate missing values from provider permission failures. Settings stored in Supabase, such as Auth and email, also need their documented Kickstart step.

Only intentionally public values belong in NEXT_PUBLIC_ fields. If server code can't read a secret, fix where it's loaded; renaming it with NEXT_PUBLIC_ would expose it in the browser. See Setup and Configuration.

Development server and port errors

If node, npm or git isn't found, install it and reopen the terminal. Compare node --version with the engines requirement in package.json. An ENOENT error mentioning package.json usually means the terminal is in the wrong folder.

If a dependency or generated Fumadocs module is missing, run npm ci again from the project folder and fix its first error. Don't copy another project's node_modules or .source.

For EADDRINUSE, or a message that Next.js chose another port, another app is already using port 3000. Stop the server you don't need, then restart this one. Don't continue on a different port: sign-in only works at the address in APP_URL.

If the login page loads but you see a database or permission error, check that Kickstart completed and that the same project keys are still in .env. A running development server doesn't mean the database is installed.

Sign-in doesn't stick

Open your app at exactly the address in APP_URL, normally http://localhost:3000. Browsers treat localhost, 127.0.0.1 and other ports as different sites, so a session created at one address isn't visible at another. Clear the site's cookies, return to the configured address and sign in again.

After deployment, sign-in emails and Google sign-in return to your live address, even when you started locally. That's expected; see Where your app runs.

Kickstart

Key and mode errors

Message: Fill STRIPE_TEST_SECRET_KEY with your Stripe sandbox Secret key.

Kickstart needs a test secret key starting with sk_test_, not a publishable (pk_) or live (sk_live_) key. Check the key's type in Stripe without sharing its value, correct the .env line using the Stripe guide, then run npm run kickstart:check. The format error should disappear and the account checks run.

Message: Stripe sandbox preflight failed. Check the test key and account/catalog/customer/subscription/invoice/Checkout/webhook/portal read permissions. No project has been created by this run.

The key may be expired, restricted, from another sandbox or missing a permission. Check which Stripe account and sandbox you copied it from, then retry the same read-only check. Don't put the live key in the test field.

For Supabase, a project key can't replace the access token. For Resend, a Sending access key can't manage templates and domains. For GitHub and Vercel, check the token's expiry, owner or team and any organization approval. Each provider's guide under Accounts covers its key.

Account and project preflight

Message: Multiple Vercel teams are accessible. Run kickstart:deploy in an interactive terminal to select one, or set optional VERCEL_TEAM_ID for unattended setup.

Run the command in a normal terminal and choose the intended team. For unattended runs, set its exact team_ ID, then run npm run kickstart:deploy -- --check. The token must have access to that team.

Kickstart asks the same way when you have several Supabase organizations or verified Resend domains. Set SUPABASE_ORGANIZATION_SLUG or the sender only when you need to skip the question.

Message: The selected US/project region has no available capacity. Set SUPABASE_REGION to an available region or retry later.

Choose an available region before the project is created, or wait and retry. Then rerun npm run kickstart:check. Once a project creation has started, changing the region won't create a second project.

Some checks show as deferred before your Supabase project exists. That means "not checked yet", not "passed". Plan limits and billing holds can still stop setup after the account checks pass.

Uncertain provider operation

Message: Project creation is unresolved. Check Supabase for the exact project name in .kickstart/bootstrap.json, then rerun once visible. No second create request will be issued; see docs/KICKSTART.md for recovery.

A network error can happen after Supabase accepted the request. Keep the .kickstart files. Look for the project name from .kickstart/bootstrap.json in your Supabase dashboard, wait until it appears, then rerun npm run kickstart. Kickstart picks up the same project and continues; it won't create a second one.

If no matching project appears, stop and ask for help with the sanitized error. Don't edit or delete the .kickstart files on the assumption that the request failed.

Message: The saved project is still starting. Rerun kickstart when healthy; its receipt prevents duplicate creation.

Wait for that project to show as healthy in Supabase, then rerun the same command. If it stays unhealthy, check Supabase's status page.

Sender and email delivery

Message: No verified sending domain is available. Verify a Resend domain and set RESEND_FROM_EMAIL, or allow automatic test mode with a local APP_URL.

Without a verified domain, Resend's test sender only delivers to the email address you use to sign in to Resend. Sign up in your app with that exact address. Emails to anyone else won't arrive, and that's expected in test mode. Check your spam folder too.

To email other people, verify a sending domain. Then run npm run kickstart:check locally or npm run kickstart:deploy -- --check when deploying, and apply the change with the matching command once the check passes. A passing check confirms the settings; send yourself a welcome, recovery and invitation email to confirm delivery.

Changed project or saved state

Message: Supabase project differs from the bootstrap receipt. Restore the original project configuration.

Message: Existing kickstart state found. Restore SUPABASE_PROJECT_REF and its receipt; no replacement project will be created.

Your .env and .kickstart files point to different projects. Restore the original values and files, for example from your backup. The keys, project reference and .kickstart files belong together as one installation. A new installation needs a fresh copy of the starter.

If a .kickstart file is unreadable, restore it from a backup. An empty file isn't a valid replacement. Keep the damaged file for diagnosis and don't share its contents publicly.

Deployment

GitHub App and repository access

Message: Repository must be private, writable, unarchived, and match the configured GitHub owner/name.

Check the owner, name, ID and token permissions. The automatic path creates a new private repository; the precreated alternative needs an empty private one. Rerun npm run kickstart:deploy -- --check after fixing access. Never point Kickstart at a repository that already has code.

When Vercel can't see the repository, check the Vercel GitHub App installation, not the GitHub token. If it's limited to selected repositories, add the new one through the link Kickstart printed, then rerun npm run kickstart:deploy. See Vercel.

Build and source errors

Message: Source changed after the Vercel connection. Push application changes through Git; use this installer copy only to resume/reconcile the original deployment.

Deployment Kickstart only publishes your first version. Clone your new repository and push later changes through Git. Don't delete the .kickstart files or force-push to make a changed folder look like a first run.

Message: GitHub contains unrecorded commits. Kickstart will not overwrite buyer changes. Use an empty initial repository or reconcile the recorded source.

The repository has commits Kickstart didn't make. Keep them. See updates after the first snapshot for the supported path.

For npm ci lockfile errors, use the Node version required by package.json with the matching package-lock.json. If you changed dependencies on purpose, update the lockfile locally, review the diff and run the build. For a failed Vercel build, find the first useful error in its build log and reproduce it locally with npm ci and npm run build.

Origin and lock recovery

After deployment, running local npm run kickstart is blocked on purpose, because your live app and local app share sign-in settings. Read active and saved origins before switching; --restore-local affects your live customers.

If .kickstart/install.lock remains after a crash, first make sure no Kickstart command is still running. Then delete only that lock file, never the other .kickstart files, and rerun the command. If a Kickstart command is still running, wait for it.

Development

Debug with VS Code

To trace a server action, stop your running development server and add this configuration to .vscode/launch.json. If the file already has configurations, add this entry to its array instead of replacing the file.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Starter: debug server",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev -- --inspect",
      "cwd": "${workspaceFolder}"
    }
  ]
}

Open Run and Debug, choose Starter: debug server and start it. Put a breakpoint in the relevant app/actions/ or app/api/ file, then trigger the request in the browser. Check the workspace ID, validation result and the current user's permission before stepping into a database call. Keep secret values out of screenshots and logs.

For browser code, use the browser's Sources and Network panels. Compare a failed request with the server terminal to see whether it failed in the browser, the server or a provider.

Style changes are not appearing

Check that you edited your app's app/globals.css or the component the page actually imports, and that the browser shows the server running from the folder you edited. Restart the development server after configuration changes and reload the page.

Use the shared CSS variables for theme colors and check both light and dark mode. Keep Tailwind class names complete, such as bg-red-500 or bg-green-500, instead of building them from fragments at runtime. Reuse the installed component patterns before adding more specific overrides.

Production requests are slow

Use the browser's Network panel to find the slow request, then compare it with Vercel's request logs. A slow image, database query and AI response each need different fixes.

Compare your Vercel function region with your Supabase database region; distance adds time to every database call. Don't move a live database to test a guess. For a long list, check filtering, pagination and indexes first. The testing guide helps you measure before and after a change.

Ask for help

Share the command you ran, your Node version, the exact error with any secrets removed, and which step failed. Say whether a provider request might have gone through before an error or timeout. Keep your .env, .kickstart files and customer data out of the report. Safe diagnostics has a template.