# Troubleshooting

URL: https://ship-and-scale.vercel.app/docs/operations/troubleshooting

Fix common setup, Kickstart and deployment problems without losing saved progress.

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 [#find-your-symptom]

| Symptom                                                 | Jump to                                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| No repository invitation, or cloning fails              | [Invitation and clone problems](#invitation-and-clone-problems)                 |
| PowerShell won't run `npm`                              | [npm is blocked in PowerShell](#npm-is-blocked-in-powershell)                   |
| Environment change is ignored or a value is missing     | [Environment variables are not loading](#environment-variables-are-not-loading) |
| Dev server will not start, wrong app or unexpected port | [Development server and port errors](#development-server-and-port-errors)       |
| Signing in sends you back to the login page             | [Sign-in doesn't stick](#sign-in-doesnt-stick)                                  |
| Stripe key or permission rejected                       | [Key and mode errors](#key-and-mode-errors)                                     |
| Multiple accounts, organizations, teams or domains      | [Account and project preflight](#account-and-project-preflight)                 |
| Project creation timed out or appears duplicated        | [Uncertain provider operation](#uncertain-provider-operation)                   |
| Emails don't arrive, or only reach you                  | [Sender and email delivery](#sender-and-email-delivery)                         |
| Missing target, mismatched key or saved state           | [Changed project or saved state](#changed-project-or-saved-state)               |
| GitHub repository invisible to Vercel                   | [GitHub App and repository access](#github-app-and-repository-access)           |
| Build, lockfile or source changed error                 | [Build and source errors](#build-and-source-errors)                             |
| Production address or stale lock                        | [Origin and lock recovery](#origin-and-lock-recovery)                           |
| Tracing a failing server action                         | [Debug with VS Code](#debug-with-vs-code)                                       |
| Theme or component edits do not appear                  | [Style changes are not appearing](#style-changes-are-not-appearing)             |
| A deployed page feels slow                              | [Production requests are slow](#production-requests-are-slow)                   |

## Getting the starter [#getting-the-starter]

### Invitation and clone problems [#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](https://cli.github.com/), run `gh auth login` and follow the prompts.
* Use [GitHub Desktop](https://desktop.github.com/), signed in with the connected account.

Don't put an access token in the clone URL. See [Setup](/docs/start/environment#get-access-to-the-starter) for the full access flow.

## Local setup [#local-setup]

### npm is blocked in PowerShell [#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](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_execution_policies) explains how to change the setting if you prefer.

### Environment variables are not loading [#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](/docs/start/environment) and [Configuration](/docs/build/configuration).

### Development server and port errors [#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 [#sign-in-doesnt-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](/docs/build/codebase#where-your-app-runs).

## Kickstart [#kickstart]

### Key and mode errors [#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](/docs/accounts/stripe), 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](/docs/accounts) covers its key.

### Account and project preflight [#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 [#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](https://status.supabase.com/).

### Sender and email delivery [#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](/docs/accounts/resend#verify-a-production-sender). 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 [#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 [#deployment]

### GitHub App and repository access [#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](/docs/accounts/vercel#connect-github).

### Build and source errors [#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](/docs/operations/deployment#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 [#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](/docs/operations/deployment#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 [#development]

### Debug with VS Code [#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.

```json title=".vscode/launch.json"
{
  "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 [#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](/docs/build/customization) before adding more specific overrides.

### Production requests are slow [#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](/docs/operations/testing) helps you measure before and after a change.

## Ask for help [#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](/docs/operations/maintenance#safe-diagnostics) has a template.