Troubleshooting

Common issues when installing, configuring, or deploying LaunchKit Pro. For deeper context see Deployment Gotchas.

---

Database not_configured on /health

Symptoms: Health JSON shows database not_configured or connection errors.

Fix:

1. Set valid DATABASE_URL in backend .env
2. Ensure PostgreSQL is running
3. Run npx prisma generate and npx prisma migrate deploy
4. Restart the API

---

User denied access on database (P1010)

Symptoms: Prisma error P1010; migrations or API fail.

Fix:

1. Create DB owned by app user (see Database Setup)
2. Grant schema privileges: GRANT ALL ON SCHEMA public TO launchkit_user;
3. Verify DATABASE_URL username, password, database name, host, and port
4. In pgAdmin: database name ≠ password — use separate fields

---

P3014 shadow database error

Symptoms: prisma migrate dev fails with P3014.

Fix:

• Buyers / install: use npx prisma migrate deploy — not migrate dev
• Developers: grant PostgreSQL CREATEDB to dev user, or configure Prisma shadow DB URL

See Database Setup.

---

nest: not found (backend build)

Symptoms: sh: 1: nest: not found during npm run build.

Fix: Run full npm ci before build. Do not use npm ci --omit=dev first. After successful build, production may run npm prune --omit=dev.

See Deployment Gotchas.

---

/auth/register returns 500

Symptoms: Registration fails during fresh install.

Fix:

1. Read backend terminal logs (first step)
2. Confirm JWT_ACCESS_SECRET and JWT_REFRESH_SECRET are set (not empty)
3. Confirm npx prisma migrate deploy succeeded
4. Verify DATABASE_URL and DB permissions (P1010)
5. Compare .env with Environment Variables

---

Frontend cannot call backend

Symptoms: Login/register network errors; API unreachable from browser.

Fix:

1. Backend running? curl http://localhost:4000/health
2. NEXT_PUBLIC_API_URL matches backend (e.g. http://localhost:4000)
3. Backend FRONTEND_URL matches browser origin (e.g. http://localhost:3000)
4. Rebuild frontend after changing NEXT_PUBLIC_*
5. No mixed HTTP/HTTPS (HTTPS page calling HTTP API)

See CORS / API URL mismatch.

---

AI provider and generation

Provider selected but API key missing

Symptoms: GET /ai/provider-status shows configured: false or generation fails with a configuration message.

Fix:

1. Confirm AI_PROVIDER matches the key you set (OPENAI → OPENAI_API_KEY, GEMINI → GEMINI_API_KEY)
2. Or switch back to AI_PROVIDER=MOCK for local testing without keys
3. Restart the API after env changes

Mock mode works but real provider fails

Symptoms: Mock generations succeed; OpenAI/Gemini requests fail.

Fix:

1. Verify the API key in your provider dashboard (valid, not expired, billing enabled)
2. Check AI_OPENAI_MODEL / AI_GEMINI_MODEL names
3. Read backend logs for sanitized provider errors
4. Confirm outbound HTTPS from your server is allowed

Demo account generation blocked

Symptoms: HTTP 403 with message containing Demo account restriction.

Expected: Public demo accounts cannot trigger real AI to protect provider credits.

Fix:

• Demo users can still browse AI UI and view sample history
• Use a registered non-demo account to test real generation
• Adjust AI_DEMO_RESTRICTED_EMAILS / AI_DEMO_BLOCK_REAL_GENERATION in server env if running your own demo policy

Test account limit reached

Symptoms: Error message contains Test account AI limit reached.

Fix:

1. Use an admin or normal account for additional testing
2. Or raise AI_TEST_USER_MONTHLY_LIMIT in server env
3. Confirm the email is listed in AI_TEST_USER_EMAILS

AI route returns 404

Symptoms: /ai/generate, /ai/history, or similar return 404.

Fix:

1. Confirm backend is updated and AI module is registered
2. Run npx prisma migrate deploy for AI migrations
3. Static routes (/ai/provider-status, /ai/templates) must be declared before dynamic :param routes in NestJS controllers

See AI Module.

---

CORS / API URL mismatch

Symptoms: Browser blocks requests; login fails with network error.

Fix:

1. Set frontend NEXT_PUBLIC_API_URL to exact backend origin
2. Set backend FRONTEND_URL to exact frontend origin
3. Add extra browser origins (staging/preview) to CORS_ALLOWED_ORIGINS comma-separated list
4. Restart both services after env changes
5. In production, use HTTPS URLs consistently

---

Prisma migration errors (general)

Symptoms: Migration fails, tables missing.

Fix:

1. Verify PostgreSQL is running and DATABASE_URL is correct
2. Run npx prisma generate
3. Buyers / production: npx prisma migrate deploy
4. Developers changing schema: npx prisma migrate dev (may need CREATEDB)
5. Check DB user permissions

---

Redis not configured / queues

Symptoms: /health shows Redis not_configured; queue errors when enabled.

Fix:

• Simple install: QUEUES_ENABLED=false — Redis optional; ignore Redis in health if not using queues
• With queues: set REDIS_URL=redis://127.0.0.1:6379, start Redis, set QUEUES_ENABLED=true, restart API
• Misconfiguration: QUEUES_ENABLED=true without running Redis causes queue worker errors — revert to false or fix Redis

See Redis & Queues.

---

401 Unauthorized

Symptoms: API returns 401 on protected routes.

Fix:

1. Send Authorization: Bearer <accessToken> header
2. Refresh token or log in again if expired
3. JWT_ACCESS_SECRET change invalidates existing tokens
4. Clear frontend session storage and re-login

---

403 Permission denied

Symptoms: Authenticated but action rejected.

Fix:

1. Check workspace role (OWNER/ADMIN/MEMBER/VIEWER)
2. Verify plan includes feature (e.g. API keys on Lite plan)
3. Demo mode may block action — check GET /demo/me
4. Admin routes require platform ADMIN role

---

Upload 413 error

Symptoms: Nginx or server rejects large uploads.

Fix:

1. Increase Nginx client_max_body_size
2. Align MAX_UPLOAD_SIZE_MB (backend) and plan limits
3. Frontend NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB is pre-validation only
4. Profile avatars are cropped to 512×512 client-side — workspace file uploads may still hit limits

---

Avatar visible at direct URL but not in app

Symptoms: Opening https://api.yourdomain.com/uploads/avatars/... works in a new tab, but the dashboard profile or topbar shows initials or a broken image.

Cause: Cross-origin resource policy or CORS mismatch between app origin (app.yourdomain.com) and API origin (api.yourdomain.com).

Fix:

1. Confirm NEXT_PUBLIC_API_URL matches the API origin serving /uploads
2. Ensure the API serves static uploads with cross-origin-friendly headers for browser <img> tags
3. Rebuild frontend after changing NEXT_PUBLIC_*
4. Hard-refresh or clear cache after avatar upload

See File Storage & Avatars.

---

NEXT_PUBLIC_API_URL mismatch

Symptoms: Frontend loads but API calls or avatar URLs point to the wrong host.

Fix:

1. Set NEXT_PUBLIC_API_URL=https://api.yourdomain.com (exact API origin, no trailing path)
2. Rebuild frontend: npm run build
3. Match backend FRONTEND_URL to the app origin

---

API docs not loading

Symptoms: /api-docs blank or 404.

Fix:

1. Confirm API_DOCS_ENABLED=true (or false if intentionally disabled)
2. Check API_DOCS_PATH (default api-docs) and API_DOCS_JSON_PATH
3. If protected mode: verify reverse-proxy basic auth credentials
4. Production/demo: use protected or disabled — see API Documentation

---

File upload path issues

Symptoms: Upload fails in production; permission errors.

Fix:

1. Ensure LOCAL_UPLOAD_DIR exists and API user can write
2. Use absolute path in production if needed
3. Check disk space

---

Email mock logs only

Symptoms: No real emails received.

Expected: EMAIL_PROVIDER=MOCK writes to email logs.

Fix for real email: Switch provider and configure SMTP/Resend/Gmail in server env only.

---

Swagger authorize fails

Fix: Use fresh token from login; Bearer scheme; token not expired.

---

Still stuck?

1. Check GET /health and admin system status (if admin)
2. Review backend logs during failed register/login
3. Compare .env against Environment Variables
4. Deployment Gotchas
5. Installation checklist