Troubleshooting

If something isn't working, start here. This page covers the issues people run into most often.

Installation and setup

Permission error when running npx stackkit

If you see a permissions error, use npx stackkit@latest instead of a globally installed version. It always fetches the latest, pre-built release.

npx stackkit@latest create my-app

Network timeout during installation

If dependency installation times out, increase npm's fetch timeout and try again:

npm config set fetch-timeout 300000

Or switch to a different package manager like pnpm, which tends to be faster:

pnpm dlx stackkit@latest create my-app

Dependencies failed to install

Delete node_modules and reinstall from scratch:

rm -rf node_modules
npm install

If you're using pnpm:

rm -rf node_modules
pnpm install

Running the dev server

Port is already in use

Kill whatever is running on the default port for your framework:

# Next.js on port 3000
lsof -ti:3000 | xargs kill -9

# Express on port 5000
lsof -ti:5000 | xargs kill -9

# React/Vite on port 5173
lsof -ti:5173 | xargs kill -9

Or specify a different port when starting:

# Next.js
PORT=3001 npm run dev

# Express
PORT=5001 npm run dev

Module issues

Incompatibility error when running add

Not all modules work with every framework. If you see a compatibility error, run stackkit list to see what's available for your project:

npx stackkit list

Full compatibility matrix:

A module doesn't seem to be working

First, check your project health:

npx stackkit doctor

If that doesn't surface the issue, try reinstalling your dependencies:

npm install

Database issues

Prisma Client is not found or outdated

Regenerate the Prisma Client after any schema change:

npx prisma generate

Database connection failed

1. Confirm your DATABASE_URL in .env is correct
2. Make sure your database server is actually running
3. Test whether Prisma can reach it:

npx prisma db push

If you see a connection refused error, the issue is with the database server, not StackKit.

MongoDB connection refused (Mongoose)

Make sure MongoDB is running on your machine:

# macOS (Homebrew)
brew services start mongodb-community

# Linux (systemd)
sudo systemctl start mongod

If you're using MongoDB Atlas, double-check that:

• Your IP address is in the Atlas allowlist
• Your username and password are correct in the connection string

Authentication issues

Better Auth: Missing secret

If you see an error about a missing or invalid secret, generate one and add it to your .env:

openssl rand -base64 32

Then set it in .env:

BETTER_AUTH_SECRET="your-generated-secret-here"
BETTER_AUTH_URL="http://localhost:5000"

Better Auth: Session not persisting

Make sure BETTER_AUTH_URL matches the exact URL you're accessing in the browser, including the port.

# Development (all frameworks)
BETTER_AUTH_URL="http://localhost:5000"

Environment variables

Variables are missing or not loading

Copy the example file and fill in your values:

cp .env.example .env

For Next.js, make sure you restart the dev server after changing .env — Next.js doesn't hot-reload environment variables.

If variables are still missing:

1. Confirm the file is named .env (not .env.txt)
2. Restart the dev server
3. Verify no quotes around values (unless needed)

Still stuck?

• Run npx stackkit doctor and share the output when asking for help
• Search existing GitHub issues
• Open a new issue with details about your setup and what you tried
• Join the Discord server for community help

Common Questions

Q: Can I use StackKit with existing projects?
A: Yes, use stackkit add to add modules.

Q: How do I update StackKit?
A: Use npx stackkit@latest - it always uses the latest version.

Q: Can I modify generated code?
A: Yes! You own all code. StackKit is not a runtime dependency.

Q: Which database should I choose?
A: Prisma for flexibility (supports multiple databases), Mongoose for MongoDB-only projects.

Q: What if my framework isn't supported?
A: See Contributing to add support.