Diagnosing Scalingo App Startup Failures After Deployment

Recognizable condition

After a successful scalingo deploy, the application does not reach a healthy state. The web dyno repeatedly restarts or stays in crashed state, and the platform logs show the process exiting quickly.

Cause / diagnostic table

Symptom in logs	Likely cause
"Error: Procfile not found" or no web process started	Missing or malformed Procfile
Buildpack compile errors (e.g., "node: command not found", "ruby: not supported")	Incompatible or outdated buildpack
ReferenceError: process.env.DATABASE_URL is undefined	Required environment variable missing or wrong
"Killed" or "Out of memory" messages shortly after start	Insufficient container size (RAM/CPU)
Connection refused to add‑on host, or add‑on shows failed state	Add‑on not provisioned or unhealthy

Ordered checks

1. Retrieve full logs

   Run the CLI command where you have access to the account:

   scalingo logs --app <app-name> --lines 200

   Look for the first error line preceding the crash. No special permissions are required beyond being a collaborator on the app.

2. Verify Procfile

   Check its existence and content:

   scalingo run --app <app-name> cat Procfile

   Expected output: a line starting with web: followed by the command that starts your server (e.g., web: npm start). If the file is missing or the line is absent, the platform cannot launch the web process.

3. Confirm buildpack

   List the buildpacks currently set:

   scalingo buildpacks --app <app-name>

   Ensure the buildpack matches your language/runtime (e.g., heroku/nodejs for a Node.js app). Mismatch often yields compile‑time errors visible in the build step of the logs.

4. Check required environment variables

   Inspect the variables defined for the app:

   scalingo env --app <app-name>

   Verify that variables such as DATABASE_URL, REDIS_URL, or any custom secrets are present and have non‑empty values. Missing variables typically cause the process to exit with a reference error during initialization.

5. Review container size

   See the current plan:

   scalingo ps --app <app-name>

   If the plan is Free or a low‑tier XS and the logs show Out of memory or Killed, consider upgrading to a larger plan.

6. Validate add‑on status

   List add‑ons and their state:

   scalingo addons --app <app-name>

   Each required add‑on should display created or running. A failed or provisioning state indicates the dependency is not ready, causing the app to crash on boot.

Fixes tied to findings

• Missing/malformed Procfile – Add a correct Procfile at the repository root, commit, and redeploy. Example for a Python Flask app:
• web: gunicorn app:app
• Wrong buildpack – Replace it with the appropriate one:
• scalingo buildpacks:set heroku/nodejs --app <app-name>
• Commit an empty change (or just push) to trigger a rebuild.
• Missing environment variable – Set it via the CLI or dashboard:
• scalingo env-set DATABASE_URL=postgres://user:pass@host:5432/db --app <app-name>
• Insufficient container size – Upgrade the plan:
• scalingo ps:scale web=1:Standard-2X --app <app-name>
• Unhealthy add‑on – Provision or repair:
• If missing: scalingo addons-add scalingo-postgresql:starter --app <app-name>
• If failing: check the add‑on’s logs with scalingo addons-log <addon-id> --app <app-name> and follow the provider’s troubleshooting guide.

Escalation criteria

If after performing the checks above the application still fails to start:

• Collect the full build and runtime logs (scalingo logs --app <app-name>) and open a support ticket with Scalingo, attaching the log excerpt.
• Indicate which of the diagnostic steps you have already completed and the exact error messages observed.
• For production‑critical services, consider deploying to a review app (scalingo create --remote review --app <app-name>-review) to isolate the issue without affecting the live environment.