Deployment Gotchas

Common setup and deployment issues for LaunchKit Pro buyers. Placeholders only — never paste real passwords or production credentials into tickets or git.

Related: Installation · Environment Variables · Redis & Queues · Troubleshooting

---

nest: not found (backend build)

Symptom:

sh: 1: nest: not found

Cause: npm ci --omit=dev (or npm install --production) ran before npm run build. @nestjs/cli is a devDependency required for nest build.

Fix:

npm ci
npx prisma generate
npx prisma migrate deploy
npm run build
npm prune --omit=dev

Install all dependencies → build → prune dev deps only after a successful build.

---

Prisma P3014 (shadow database error)

Symptom:

Error: P3014
Prisma Migrate could not create the shadow database...

Cause: prisma migrate dev needs a temporary shadow database; the PostgreSQL user may lack CREATEDB.

Fix for buyers / production:

npx prisma migrate deploy

Do not use migrate dev for marketplace install or production.

Fix for developers using migrate dev: grant CREATEDB to the dev user, or configure Prisma shadowDatabaseUrl.

See Database Setup.

---

Prisma P1010 (access denied)

Symptom:

Error: P1010
User was denied access on the database...

Cause: DB user does not own the database or lacks privileges on the public schema.

Fix:

CREATE USER launchkit_user WITH PASSWORD 'replace_with_secure_password';
CREATE DATABASE launchkit_app OWNER launchkit_user;
GRANT ALL PRIVILEGES ON DATABASE launchkit_app TO launchkit_user;
GRANT ALL ON SCHEMA public TO launchkit_user;

Verify DATABASE_URL matches username, password, host, port, and database name.

---

/auth/register returns 500

Symptom: Registration fails with HTTP 500 during fresh install.

Common causes:

Cause	Check
JWT secrets missing	JWT_ACCESS_SECRET and JWT_REFRESH_SECRET set in .env
Migrations not applied	npx prisma migrate deploy completed successfully
Wrong DATABASE_URL	User, password, database name, host
DB permissions	P1010 — see above
Startup / seed errors	Read backend terminal logs on boot and on register

What to do: Check backend logs first, then compare .env with Environment Variables.

---

Redis / queues enabled without Redis

Symptom: Queue startup errors; admin queue status shows startupError; test jobs not queued.

Cause: QUEUES_ENABLED=true but Redis is not running, or REDIS_URL / REDIS_HOST is missing or wrong.

Fix:

• Simplest: QUEUES_ENABLED=false (default) — no Redis required; app starts cleanly
• With queues: install Redis, set REDIS_URL=redis://127.0.0.1:6379 (or REDIS_HOST=127.0.0.1), verify redis-cli ping → PONG, restart API
• Confirm logs show Registering BullMQ queues: email, webhook, notification, maintenance, ai

Previous issue: “BullMQ queues not registered” when BullMQ was skipped at startup but validation still expected queues. Current builds use shared bootstrap resolution to avoid this — see Background Queues.

---

Upload 413 (Nginx body size)

Symptom: File upload fails with HTTP 413.

Fix: Align limits on all layers:

Layer	Setting
Backend	MAX_UPLOAD_SIZE_MB=10
Frontend	NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB=10
Nginx	client_max_body_size 10M;

Restart Nginx after changes.

---

API docs — disabled / public / protected

Mode	Configuration
Disabled	API_DOCS_ENABLED=false
Public	API_DOCS_ENABLED=true
Protected	API_DOCS_ENABLED=true + Nginx auth_basic (recommended on production/demo)

Use placeholder credentials only — never commit real docs passwords.

See API Documentation.

---

CORS origin mismatch

Symptom: Browser blocks API calls; login fails with CORS errors.

Cause: Backend FRONTEND_URL does not match the URL in the browser.

Fix:

FRONTEND_URL=http://localhost:3000
APP_URL=http://localhost:4000

(Some guides call the frontend origin app frontend URL — the backend variable name is FRONTEND_URL.)

Restart backend after changing env.

---

Frontend NEXT_PUBLIC_API_URL mismatch

Symptom: Frontend loads but API calls fail or hit wrong host.

Fix:

NEXT_PUBLIC_API_URL=http://localhost:4000

Rebuild frontend after changing any NEXT_PUBLIC_* variable.

See Troubleshooting.

---

Avatar loads at direct URL but not in dashboard

Symptom: Avatar file opens at https://api.yourdomain.com/uploads/... but profile/topbar shows initials.

Fix: Align NEXT_PUBLIC_API_URL with API origin; ensure cross-origin headers allow browser images from app domain. Rebuild frontend after env changes.

See File Storage & Avatars and Troubleshooting.

---

Health shows database: not_configured

Symptom: /health reports database not configured.

Fix: Set valid DATABASE_URL, ensure PostgreSQL is running, run migrate deploy, restart API.

---

Still stuck?

1. curl http://localhost:4000/health
2. Backend logs during register/login
3. Troubleshooting
4. Installation checklist