Troubleshooting

Installation Issues

"Command not found" after global install

Problem: You installed the CLI globally, but your shell can't find better-ts-stack.

Solution: Add npm's global bin folder to your PATH.

# Show npm's global folder
npm config get prefix

# Add its bin folder to PATH in ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

Permission denied on Linux/Mac

Problem: You get EACCES errors when installing globally.

Solution: Don't use sudo. Point npm at a folder in your home directory instead:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

npm install -g better-ts-stack

Project Generation Issues

"Target directory is not empty"

Problem: A folder with the project name already exists and contains files.

Solution: Run the CLI again with a different project name, or move or delete the existing folder first.

"Invalid project name"

Problem: The CLI rejects the project name.

Solution: Use only lowercase letters, numbers, and hyphens, and don't start or end the name with a hyphen.

• Valid: my-api, cool-app-v2, customer-portal
• Invalid: my app (contains a space), MyApp (uppercase letters), customer_portal (underscore), .hidden (starts with a dot), or an empty name

Database Issues

"Cannot connect to database"

Problem: The app can't connect to PostgreSQL or MongoDB.

Solution: Check that the database is running and that the URL in .env is correct.

# Check whether PostgreSQL is running
pg_isready

# Start PostgreSQL (Mac with Homebrew)
brew services start postgresql

# Start PostgreSQL (Linux)
sudo service postgresql start

The connection string goes in .env:

DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

If the app runs in Docker, localhost points at the container, not your machine. See the Docker module.

Prisma migration errors

Problem: npm run prisma:migrate fails.

Solution:

# Reset the database (deletes all data)
npx prisma migrate reset

# Or create a new migration
npx prisma migrate dev --name fix_migration

# Or push the schema without creating a migration
npx prisma db push

Runtime Issues

"Port 3000 already in use"

Problem: Another process is using port 3000.

Solution: Stop that process, or start the app on another port.

# Linux/Mac: find and stop the process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
PORT=3001 npm run dev

TanStack Start: CSS and JS return 404 after npm start (Windows)

Projects generated before 2.1.0 serve production builds with srvx. On Windows, Node.js 24 releases before 24.20 report different device IDs for the same file depending on how it is read, and srvx refuses every static file, so pages load without styles or client JavaScript. Upgrade Node.js to 24.20 or later, or move the project to Nitro as 2.1.0 does (see the upgrade notes). Projects generated with 2.1.0 or later are not affected.

"Cannot find module"

Problem: Node or TypeScript can't find a module.

Solution: Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

In a Prisma project, also run npm run prisma:generate. The generated client is not created until you do.

If the error only shows in your editor, restart the TypeScript server. In VS Code, open the command palette and run TypeScript: Restart TS Server.

TypeScript Issues

Type errors in generated code

Problem: TypeScript reports errors right after generation.

Solution: Check the TypeScript version. The templates use TypeScript 6.0, and typescript-eslint does not support TypeScript 7 yet.

npx tsc --version

# If it isn't 6.0.x:
npm install -D typescript@~6.0.3

npm run type:check

"Property does not exist on type"

Problem: Type definitions are missing or out of date.

Solution:

# Install missing type packages
npm install -D @types/express @types/node @types/cors

# Regenerate the Prisma client (Prisma projects only)
npm run prisma:generate

Docker Issues

"Docker daemon not running"

Problem: Docker commands fail.

Solution: Start Docker, then check that it responds.

# Mac: start Docker Desktop
open -a Docker

# Linux
sudo systemctl start docker

# Check that Docker is running
docker ps

Container fails to start

Problem: The container exits right after starting.

Solution: Read the logs first. They usually show the cause, such as a missing environment variable or an unreachable database.

# Show container logs
npm run docker:logs

# Rebuild without cache
docker compose build --no-cache

Compose reads .env, so make sure it exists and that its database URLs work from inside the container.

Auth Issues

"Invalid token" errors

Problem: Requests with a JWT are rejected.

Solution:

• Check that JWT_SECRET is set in .env. The CLI writes a random value there.
• Tokens expire after JWT_EXPIRES_IN (default 1h). Log in again to get a new one.
• Send the token as Authorization: Bearer <token>.
• Restart the server after you change .env.

Performance Issues

Slow TypeScript builds

Problem: npm run build takes a long time.

Solution: Turn on incremental compilation in tsconfig.json:

{
  "compilerOptions": {
    "incremental": true
  }
}

During development, npm run dev uses tsx watch, which skips type checking and restarts quickly.

Large node_modules

Problem: node_modules takes up a lot of disk space.

Solution: pnpm stores packages once and links them into each project. Choose pnpm when you generate the project, or switch later with pnpm install.

Getting Help

If you're still stuck:

1. Check versions. You need Node.js 24 or later (node --version).
2. Search GitHub Issues for the same error.
3. Make a minimal reproduction. Generate a fresh project with the fewest options that still show the problem.