Skip to content
create-bsv-app

Reference

Errors

Every error the CLI and the generated code can throw, grouped by where it comes from, with what it means and what to do.

The generated helpers throw plain Errors with a fixed message. There are no custom error classes, so match on the message. For step-by-step fixes, see Troubleshooting.

ts
try {
  await 
const login: () => Promise<{
    identityKey: string;
}>
login()
} catch (var err: unknownerr) {
  const const message: stringmessage = var err: unknownerr instanceof var Error: ErrorConstructorError ? var err: Errorerr.Error.message: stringmessage : 
var String: StringConstructor
(value?: any) => string
String(var err: unknownerr)
  if (const message: stringmessage.String.startsWith(searchString: string, position?: number): booleanstartsWith('login failed:')) {
    // the server answered 401: sign again, or check the server's identity
  } else if (const message: stringmessage.String.startsWith(searchString: string, position?: number): booleanstartsWith('API ')) {
    // network or response limits: see the apiClient.ts table below
  } else throw var err: unknownerr
}

CLI#

Config problems are prefixed Invalid config: and exit with code 1.

Message Meaning
a new project needs at least a frontend or a backend custom starter with no stack. Pick full-stack, or pass --frontend and/or --backend
target directory is not empty: … new mode only writes into an empty folder. Use another folder or add mode
unknown starter: … / unknown capability: … typo in an id. See Starters and Capabilities
starter … is a complete example and does not accept generated capabilities drop --capabilities for complete examples
cannot infer separate client/server targets from a single package containing both react and express; use --file with explicit targets use --file with targets
name is required a --file config needs "name"
--network must be main, test, or ttn (and the same for --mode, --frontend, --backend, --package-manager) invalid flag value
… requires a value / unknown option: … / unexpected argument: … flag syntax. --help lists every flag
config file not found: … / cannot read config file: … / invalid JSON in … the --file path or contents
targets.client must be a safe relative path / invalid bsvDir: … no absolute paths, no ..
command failed (…): … a step such as git clone or npm install failed. Its own output is just above

apiClient.ts#

Thrown by apiFetch and readApiJson in the browser.

Message Meaning
API endpoint must be a safe absolute path the path has a query string, .., or characters outside A-Z a-z 0-9 / _ -
API request body must be a string pass JSON.stringify(...)
API request exceeds the byte limit request body over 1 MiB
API response exceeds the byte limit response over 1 MiB. Paginate
API response has an invalid Content-Length / API response length does not match Content-Length a broken proxy or server
API response changed network authority the response came from another origin (redirects are refused)
API response is not valid UTF-8 / API response is not valid JSON readApiJson couldn't parse it
AbortError no complete response within 10 seconds

Identity and login#

Message From Meaning
failed to fetch server identity: <status> getServerIdentity GET /api/identity didn't return 2xx. Is the server up?
server returned an invalid identity response serverIdentity.ts the response wasn't exactly { identityKey }
server returned an invalid identity key serverIdentity.ts not a valid compressed public key
connect a wallet first (initializeWallet / relay) useWalletLogin login() called with no wallet
connect a wallet first useSignedRequest signedFetch() called with no wallet
login failed: <status> useWalletLogin the server rejected the proof
server returned another wallet identity login the verified key isn't the connected wallet's
No authenticated desktop wallet found walletAcquisition.ts caught internally; the UI moves to No desktop wallet found
useWallet must be used within WalletProvider WalletContext.tsx wrap your app in <WalletProviders>
useWalletConnection must be used within WalletConnectionProvider WalletConnectionContext.tsx same

Server responses#

Status Body Meaning
401 { "error": "invalid proof" } the proof failed: why
400 from express.json malformed JSON, or a body over 64 kB

Client config#

Thrown when the client bundle loads, which shows as a blank page.

  • VITE_API_URL is required in production
  • VITE_API_URL must be credential-free HTTPS (or exact HTTP localhost development)
  • VITE_BSV_NETWORK must be main, test, or ttn

Server config#

Thrown at startup.

  • SERVER_PRIVATE_KEY is required in production
  • SERVER_PRIVATE_KEY must use its canonical encoding
  • CLIENT_ORIGIN is required in production
  • CLIENT_ORIGIN must be credential-free HTTPS (or exact HTTP localhost development) origin
  • PORT must be an integer from 1 to 65535
  • BSV_NETWORK must be main, test, or ttn
  • JWT_SECRET must contain at least 32 bytes (only if you add the session pattern)