Application doesn't start

Start with the basics before anything else:

• Confirm dependencies actually finished installing without errors, and that you're using the runtime version your build's documentation specifies.
• Confirm your .env file exists and is filled in — a missing environment file is one of the most common reasons an app fails to boot. See below.
• Check whether another process is already using the port your app is trying to start on.
• Read the actual startup error in your terminal/logs before changing anything — it almost always names the specific missing piece.

Missing or incorrect environment variables

Your build ships an example environment file you copy from, not a working .env on its own:

cp .env.example .env

If the app starts but behaves oddly (auth failing, database not connecting, integrations not working), compare your filled-in .env against .env.example to make sure every key it defines has a real value in yours, and that you restarted the app after editing it — most runtimes only read environment variables at startup.

Database connection problems

If you see a database/connection error:

• Double-check your DATABASE_URL (or equivalent) matches your actual database host, port, name, username and password — a typo here is the most common cause.
• Confirm the database server itself is actually running and reachable from where your app is deployed (same network/host, correct firewall rules).
• Confirm the database and user referenced in your connection string actually exist and that user has permission to connect.

Migration / setup-step issues

If your included migration or setup step fails partway through, don't guess — read the exact error, since it will usually point at a specific table, permission or connection problem rather than the migration tooling itself. Fix that underlying issue (usually one of the database connection problems above) and re-run the same migration/setup step from your Installation Guide.

Warning: never drop, reset or re-seed a database that already has real production data on it as a generic troubleshooting step. If a reset is genuinely necessary, do it only on a fresh/non-production database, and take a backup first.

Login / Founder setup issues

If you can't log in as Founder/Admin, confirm the first Founder/Admin account was actually created during your setup step — if that step was skipped or failed, there's no owner-level login yet to sign in with. Re-run the Founder/setup step from your Installation Guide rather than trying to work around it. Never share a real password, password hash or authentication secret anywhere outside your own team, including in a support request.

Production build/start issues

If the app works in development but fails when built/started for production, check that:

• All required environment variables are set in the production environment itself, not just locally — a value only present in your local .env won't exist on the server unless you've set it there too.
• You're running the actual production build/start commands from your Installation Guide, in order, rather than the development ones.
• Any secret used in production (authentication secret, database credentials, third-party API keys) is a real, freshly generated value — never a value copied from an example/template file.

Still stuck?

For anything not covered here, the written Installation Guide, video walkthrough and “AI Setup Prompt” bundled with your download stay accurate to your specific version where this general page can't be. Use “Still need help? Ask BitzStack AI” below, or the contact form, if you're still stuck.