# Troubleshooting

> Every error message we know of, quoted exactly, with what causes it and how to fix it. Search the page for the text you're seeing.

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

**Tip:** press <kbd>⌘</kbd> <kbd>F</kbd> (or <kbd>Ctrl</kbd> <kbd>F</kbd>) and paste your error. Headings below are the literal messages.

## Scaffolding

### `Invalid config: a new project needs at least a frontend or a backend`

You used the `custom` starter, its default, without choosing a stack. `custom` starts with no frontend and no backend. Either pick a named starter or choose one:

```bash
npx create-bsv-app@latest my-app --starter full-stack --yes
# or
npx create-bsv-app@latest my-app --starter custom --frontend react --backend express --yes
```

### `target directory is not empty: … new projects scaffold into an empty directory`

`new` mode only writes into an empty folder (a lone `.git` or `bsv-scaffold.json` is allowed). Pick a new folder name, or, to add capabilities to the project that's there, use [add mode](https://createbsvapp.vercel.app/docs/add-to-existing):

```bash
npx create-bsv-app@latest add --capabilities wallet-login --yes
```

### `Invalid config: unknown starter: …`

Starter ids are lowercase and exact:

`custom`, `react`, `express`, `full-stack`, `brc102-frontend`, `brc102-backend`, `pollr`, `meter`, `metamarket`, `todo`, `marscast`, `coinflip`, `postboard`, `locksmith`, `peerpay`, `atfinder`

See [Starters](https://createbsvapp.vercel.app/docs/starters) for what each one is.

### `Invalid config: unknown capability: …`

Valid ids are `wallet-connect`, `wallet-login` and `signed-requests`. Separate them with commas and no spaces: `--capabilities wallet-login,signed-requests`.

### `Invalid config: starter meter is a complete example and does not accept generated capabilities`

Complete examples are cloned as they are, so drop `--capabilities`. If you want capabilities, use a [generated starter](https://createbsvapp.vercel.app/docs/starters#generated-starters).

### `cannot infer separate client/server targets from a single package containing both react and express`

Add mode found one `package.json` with both React and Express, and can't guess where client and server files go. Pass a config with explicit `targets`: [here's the exact file](https://createbsvapp.vercel.app/docs/add-to-existing#how-the-cli-finds-your-app).

### `Invalid config: name is required`

A `--file` config needs `"name"`, even in add mode.

### `Invalid config: --network must be main, test, or ttn`

The same pattern applies to `--mode`, `--frontend`, `--backend` and `--package-manager`: the message lists the allowed values. `… requires a value` means a flag is missing its argument, and `unknown option: …` means a typo. `npx create-bsv-app --help` prints every flag.

### `command failed (…): git clone …`

Complete-example starters are cloned with `git`. Install git, check that you can reach github.com, and run again into an empty folder.

### The output says "cd client, npm install, npm run dev". Is that for me?

No. That's create-vite's own message, printed halfway through. Follow the final **Next:** block, which says `cd my-app` and `npm run dev`. Dependencies are already installed.

### It installed with npm but I use pnpm

The CLI doesn't detect the package manager that launched it. Pass `--package-manager pnpm` (or `yarn`, or `bun`). In an existing project with a lockfile, installs follow the lockfile.

### Odd failures on Node.js 20 or older

create-bsv-app requires Node.js 22 or newer (npm may print an `EBADENGINE` warning). Check with `node -v`. Upgrade with `nvm install 22`, `fnm install 22`, or from nodejs.org. Older versions may half-work and then fail in confusing ways.

## Build

### Client build fails with `TS2304: Cannot find name 'requireIdentityKey'` {#client-build-fails}

A known issue in create-bsv-app 1.1.2. The generated client has three type errors that `npm run dev` doesn't catch (Vite doesn't type-check) but `npm run build` does:

```text
src/bsv/apiClient.ts(84,25): error TS2345: Argument of type 'Uint8Array<ArrayBufferLike> | null' is not assignable to parameter of type 'BodyInit | null | undefined'.
src/bsv/useWalletLogin.tsx(15,26): error TS2304: Cannot find name 'requireIdentityKey'.
src/bsv/WalletLogin.tsx(6,54): error TS6133: 'requireIdentityKey' is declared but its value is never read.
```

The second one is also a **runtime** bug: `useWalletLogin().login()` throws `ReferenceError: requireIdentityKey is not defined`. The demo login page doesn't use the hook, which is why the demo still works. Three one-line fixes:

::: code-group
```ts [client/src/bsv/useWalletLogin.tsx]
import { getServerIdentity, readIdentityKeyResponse } from './serverIdentity.js' // ← remove this line
import { getServerIdentity, readIdentityKeyResponse, requireIdentityKey } from './serverIdentity.js' // ← add this line
```
```ts [client/src/bsv/WalletLogin.tsx]
import { getServerIdentity, readIdentityKeyResponse, requireIdentityKey } from './serverIdentity.js' // ← remove this line
import { getServerIdentity, readIdentityKeyResponse } from './serverIdentity.js' // ← add this line
```
```ts [client/src/bsv/apiClient.ts]
async function readBoundedBody (response: Response): Promise<Uint8Array> { // ← remove this line
async function readBoundedBody (response: Response): Promise<Uint8Array<ArrayBuffer>> { // ← add this line
```
:::

With those three changes, `npm run build` passes. We verified it on a fresh 1.1.2 full-stack scaffold.

## Wallet & connection {#wallet}

### "No desktop wallet found" even though I installed one

`WalletClient('auto')` looks for a wallet running on this machine. Make sure [BSV Browser](https://browser.bsvb.tech/) is **open and unlocked**, then click **Connect wallet** again. Still nothing? Choose **Connect with a mobile wallet** and scan the QR code with BSV Browser on your phone.

### `failed to fetch server identity: …` or `TypeError: Failed to fetch`

The client can't reach the server, or CORS blocked it. Check in this order:

1. **Is the server running?** `curl http://localhost:3000/health` should print `{"status":"ok"}`.
2. **Are you on exactly `http://localhost:5173`?** The server only allows `CLIENT_ORIGIN`, which defaults to `http://localhost:5173`. Opening `127.0.0.1:5173`, or getting moved to `:5174` because 5173 was busy, is a different origin, and CORS blocks it. Free the port, or set `CLIENT_ORIGIN` to match.
3. **Is `VITE_API_URL` right?** Restart `npm run dev` after changing `.env`. Vite reads it at startup.

### The QR code never appears ("Generating code…")

The mobile relay lives on the server (`/api/session`, `/ws`). Same checks as above. In production, make sure your host forwards WebSocket upgrades: see [Deploy](https://createbsvapp.vercel.app/docs/deploy#two-hosting-rules).

### Login or signed request returns `401 {"error":"invalid proof"}`

The server rejected the proof. In order of likelihood:

- **The server restarted** between fetching its identity and receiving the proof. Without `SERVER_PRIVATE_KEY` it gets a new identity on every start. Refresh the page, or [set a key](https://createbsvapp.vercel.app/docs/environment#generate-a-server-key).
- **`action` or `body` differ** between client and server. They must match exactly. See [capabilities](https://createbsvapp.vercel.app/docs/capabilities#signed-requests).
- **The proof was reused or is stale.** Each proof is single-use and expires after 2 minutes. Sign a fresh one per request.
- **Your clock is off** by more than 30 seconds. Sync your system time.
- **The nonce store is full.** The in-memory store holds 10,000 recent nonces and refuses new ones until they expire. Under sustained load, [move it to Redis](https://createbsvapp.vercel.app/docs/security#replay-protection-across-instances).

### `server returned another wallet identity`

The identity the server verified isn't the wallet you connected, usually because you switched accounts in the wallet mid-session. Reload and connect again.

### `API endpoint must be a safe absolute path`

`apiFetch` only accepts paths made of letters, numbers, `/`, `_` and `-`. **Query strings aren't allowed.** Put parameters in the path (`/api/notes/42`), or in a POST body.

### `API request body must be a string`

`apiFetch` takes a string body. Wrap objects with `JSON.stringify(...)` and set `content-type: application/json`.

### `API response exceeds the byte limit`

`apiFetch` caps responses at 1 MiB and requests at 1 MiB, and times out after 10 seconds. Paginate large responses, or change the limits at the top of `apiClient.ts` if you really need to.

## Production

### White screen in production, console says `VITE_API_URL is required in production`

`VITE_API_URL` wasn't set when you ran `vite build`. It's baked in at build time. Rebuild with it set. It also has to be `https://`, or you'll see `VITE_API_URL must be credential-free HTTPS (or exact HTTP localhost development)`.

### `SERVER_PRIVATE_KEY is required in production` / `CLIENT_ORIGIN is required in production`

Set them in the server's environment. See [Deploy](https://createbsvapp.vercel.app/docs/deploy#1-deploy-the-server). `CLIENT_ORIGIN` must be a bare `https://` origin: no path, no trailing slash, no credentials.

### `SERVER_PRIVATE_KEY must use its canonical encoding`

The key has to be in the exact format `PrivateKey.toString()` prints: lowercase hex. Uppercase hex or extra whitespace fail. Regenerate with the [one-liner](https://createbsvapp.vercel.app/docs/environment#generate-a-server-key), or re-print your existing key through it.

### `PORT must be an integer from 1 to 65535`

`PORT` has to be a plain number with no leading zeros.

### A refresh on `/login` returns 404

Your static host needs a single-page-app fallback to `index.html`. [Config for Vercel, Netlify and nginx](https://createbsvapp.vercel.app/docs/deploy#single-page-routing).

## Still stuck?

- Read your project's `AGENTS.md`. It documents every generated function.
- Ask an assistant with the full docs: copy [/llms-full.txt](https://createbsvapp.vercel.app/llms-full.txt) into it.
- Open an issue on [bsv-blockchain/ts-stack](https://github.com/bsv-blockchain/ts-stack/issues) with your `bsv-scaffold.json`, your Node version and the full error.