Troubleshooting App Platform

Common issues and how to fix them.

App Not Starting

Check logs first:

• Go to Services > PaaS > Your App > Logs
• Look for error messages in the last few lines

Common causes:

• App not listening on process.env.PORT — most common mistake
• Missing dependencies in package.json or requirements.txt
• Syntax error in code
• Missing environment variables

Fix: Ensure your app binds to the PORT environment variable:

// Node.js
const port = process.env.PORT || 3000;
app.listen(port);

# Python
port = int(os.environ.get('PORT', 5000))
app.run(host='0.0.0.0', port=port)

Build Failing

Check build logs:

• Go to Deploys tab → click failed deployment → view logs

Common causes:

• package.json or requirements.txt not in repo root
• Node.js/Python version mismatch (specify in engines or runtime.txt)
• Private npm packages without auth token
• Dockerfile syntax errors

Fix for Node.js version:

// package.json
{
  "engines": { "node": "22.x" }
}

Fix for Python version:

# runtime.txt
python-3.12.x

Custom Domain Not Working

1. Verify DNS: Run dig myapp.example.com — should show apps.colosoft.com CNAME
2. Wait for propagation: DNS changes can take up to 48 hours
3. Check verification: Go to Domains tab — domain should show "Verified"
4. SSL pending: Certificate issues after DNS propagation — wait 5-10 minutes

App Crashing / Restarting

• Auto-restart happens within seconds of a crash
• Check Logs for the error that caused the crash
• Common cause: unhandled promise rejection or out-of-memory
• If OOM: upgrade your plan for more RAM

502 Bad Gateway

• App is starting up (wait 30 seconds)
• App crashed and is restarting (check logs)
• App listening on wrong port (must use PORT env var)

Deployment Stuck

• Check Deploys tab for build status
• If stuck for more than 5 minutes, the build may have timed out
• Simplify your build step or contact support

Environment Variables Not Working

• Verify variable is set in Env Vars tab
• App restarts automatically after adding/changing vars
• Variable names are case-sensitive: DATABASE_URL ≠ database_url
• Check for trailing whitespace in values

Need More Help?

• Contact support via live chat or support ticket
• Include your app name and the error message from logs
• Screenshots of the error help us debug faster