Troubleshooting

This guide collects the most common issues encountered when running coldstart or working with a generated project, along with their fixes.

Requirements check

Before anything else, make sure your environment meets the requirements.

pnpm version

Coldstart requires pnpm 10+.

pnpm --version

If you see a version below 10, upgrade:

npm install -g pnpm@latest
# or via corepack (recommended)
corepack enable
corepack prepare pnpm@latest --activate

Node version

Coldstart requires Node.js 24+ (LTS).

node --version

If you see a version below 24, install Node 24:

nvm install 24
nvm use 24

Or via Homebrew on macOS:

brew install node@24

Port conflicts

Generated projects bind a few default ports in development:

If one of these ports is already in use, pnpm dev will fail to start. Free the port, or use the portless fallback described below.

lsof -i :3000

Portless issues

Coldstart generates projects using portless to expose stable HTTPS URLs like https://web.<name>.localhost in development. If portless fails (certificate issues, proxy not starting, DNS issues), fall back to plain HTTP:

PORTLESS=0 pnpm dev

Or use the pre-wired fallback script:

pnpm dev:no-tls

This serves the web app at http://localhost:3000 and the API at http://localhost:3001 without TLS.

Missing environment variables

All apps use @t3-oss/env to validate environment variables at startup. A typical error looks like:

❌ Invalid environment variables:
{
  DATABASE_URL: [ 'Required' ],
  BETTER_AUTH_SECRET: [ 'Required' ]
}

Fix

Copy the example file and fill in the values:

cp .env.example .env

Required variables vary per project, but typical ones are:

Generate a secret with:

openssl rand -base64 32

pnpm install fails

Network errors

If you see ERR_PNPM_FETCH or timeouts, it's usually a registry/network issue:

pnpm store prune
pnpm install

Peer dependency warnings

Coldstart projects pin versions to keep the monorepo consistent. If you see peer warnings, run:

pnpm install --strict-peer-dependencies=false

Then open an issue on GitHub with the output so we can fix the pinning.

Workspace resolution errors

If pnpm complains about missing workspaces:

rm -rf node_modules **/node_modules
pnpm install

check-types errors

The repo runs tsc --noEmit across all packages via pnpm check-types. Common causes:

Cannot find module

Most often this is a missing workspace dependency. Check package.json of the importing package and make sure the target package is listed under dependencies:

{
	"dependencies": {
		"@your-scope/db": "workspace:*"
	}
}

Then reinstall:

pnpm install

Drizzle / Better Auth types out of date

If you edited a schema, regenerate types:

pnpm --filter @your-scope/db run generate
pnpm --filter @your-scope/api run auth:generate

Build failures

Next.js: ENOENT .next/server/...

Delete the .next directory and rebuild:

rm -rf apps/web/.next
pnpm --filter web run build

Expo: Metro bundler fails

Clear the Metro cache:

pnpm --filter mobile run start -- --clear

Still stuck?