Troubleshooting: My Site Won't Deploy

The launch console streams every step. Look for the first red line — that's the root cause. Common patterns:

• 'npm install failed' → dependency issue

• 'npm run build failed' → build error

• 'Port not bound' → app isn't listening on the expected port

• 'Container exited' → runtime crash

Run this in your project root:

npm install && npm run build && npm start

If it fails locally, MoonBase will fail too. Fix it locally first. If it passes locally but fails on MoonBase, read on.

If your app throws 'missing env var' errors, add them in the env vars dialog during upload. Required secrets (database URLs, API keys) must be provided — MoonBase cannot guess them.

Check your code for process.env.SOMETHING and ensure each one is set.

MoonBase runs the start script from your package.json. If your start script is wrong or missing, the Compatibility Engine proposes a fix (Tier 2 consent). Common issues:

• package.json has no 'start' script → add one: "start": "node dist/index.js"

• Start script uses dev mode → should use production: "start": "next start -p $PORT"

Your app MUST listen on the PORT environment variable, not a hardcoded port. MoonBase injects PORT automatically.

Express: app.listen(process.env.PORT || 3000)

Next.js: 'next start -p $PORT' in package.json scripts.start

The Compatibility Engine detects and fixes most port issues automatically (Tier 1). For stubborn cases it asks consent (Tier 2).

MoonBase defaults to Node.js 20. If your app requires a specific version, add an .nvmrc or engines field in package.json:

{ "engines": { "node": ">=18" } }

The Compatibility Engine reads engines.node and selects the right version.

Every deploy gets a unique TRK-ID (shown in the console and error screen). Email [email protected] with your TRK-ID and we can find the full build log and diagnose the issue.