Diagnosing Scalingo App Startup Failures Caused by Environment Variable Issues

Recognizable condition

When you push a release to Scalingo, the deployment logs show the container exiting immediately or the application failing to bind to its expected services. Typical log snippets include:

• "Error: missing DATABASE_URL"
• "redis: dial tcp: lookup redis on 127.0.0.1:53: no such host" (indicating REDIS_URL is empty or malformed)
• "env: value too long" or truncation warnings
• "No start command defined" when the Procfile or start script is missing

The application may appear to build successfully, but the web or worker dyno crashes shortly after start.

Cause / diagnostic table

Symptom in logs	Likely cause	Quick check
Missing variable name (e.g., DATABASE_URL)	Variable not defined or add‑on not attached	Run scalingo env and look for the name
Connection refused or host lookup failure	Variable present but contains leading/trailing spaces, newlines, or wrong format	Inspect the raw value with scalingo env | grep VAR_NAME
Truncation warning or value cut off	Variable exceeds Scalingo’s ~4 KB per‑variable limit	Check length: echo -n $VAR_NAME | wc -c locally or via a one‑off run
"No start command defined"	No Procfile, package.json start script, or Dockerfile CMD	Verify repository contains a valid start declaration
Add‑on URL variable empty	Add‑on not provisioned or failed to attach	List add‑ons: scalingo addons

Ordered checks

1. List all environment variables

   Run scalingo env (requires API token with admin or deploy scope). Verify that each variable your code expects appears in the output.

   scalingo env --app my-app

2. Inspect recent logs for variable‑related errors

   Fetch the last 100 lines of deployment and runtime logs:

   scalingo logs --lines 100 --app my-app

   Look for messages that mention the variable name, "null", "empty", or "invalid".
3. Confirm add‑on attachment

   If your app relies on a service (e.g., Redis, PostgreSQL), ensure the add‑on is present and its plan is active:

   scalingo addons --app my-app

   The output should list the add‑on and show a status like "provisioned".
4. Check variable formatting

   For each suspect variable, retrieve its raw value and look for hidden characters:

   scalingo env --app my-app | grep DATABASE_URL

   You can also pipe through cat -A locally after exporting to see spaces (shown as ␣) or newlines ($).
5. Verify size limits

   If you suspect a large value (e.g., a JSON config), compute its length:

   echo -n "$VALUE" | wc -c

   Ensure it is below 4096 bytes. If not, consider storing the data elsewhere (e.g., in a file attached via a buildpack or a separate add‑on) and reference it with a shorter key.
6. Validate start command

   Check for a Procfile, package.json "scripts.start", or Dockerfile CMD. If none exist, the platform cannot launch a process.

Fixes tied to findings

Missing variable

• Define it via the dashboard or CLI:

scalingo env-set DATABASE_URL=postgres://user:pass@host:5432/db --app my-app

If the variable should come from an add‑on, provision or re‑attach the add‑on:

scalingo addons-add postgres:hobby-dev --app my-app

Malformed value (spaces, newlines)

• Remove unwanted characters. The safest way is to unset and set again:

scalingo env-unset REDIS_URL --app my-app
scalingo env-set REDIS_URL=redis://:password@host:6379 --app my-app

When setting via the CLI, wrap the value in quotes to preserve internal spaces if they are intentional.

Value exceeds 4 KB limit

• Split the data: store the large payload in a file attached to the slug (e.g., via a custom buildpack) and keep only a reference (like a path) in the environment.
• Alternatively, use an add‑on that provides object storage and store the payload there, keeping only the bucket/key in the env.

Add‑on not attached

• Provision the missing add‑on and ensure it is attached:

scalingo addons-add redis:hobby-dev --app my-app
scalingo addons-attach REDIS_URL --app my-app

No start command

• Add a Procfile with a line like web: npm start (adjust for your language) or define "start": "node server.js" in package.json.
• Commit and push; the platform will detect the command on the next build.

Escalation criteria

If after performing the checks and applying the fixes the application still fails to start, consider the following escalation steps:

1. Review build logs – a failed buildpack or Docker step may hide the real issue. Run scalingo logs --post-deploy to see the full build output.
2. Check total variable count – Scalingo limits the number of vars per app (typically 64). If you exceed this, deployment will be rejected with a clear message. Remove unused vars or consolidate them.
3. Test locally with the exact env – run a container that mimics the Scalingo runtime:

docker run --rm -e DATABASE_URL="$DATABASE_URL" -e REDIS_URL="$REDIS_URL" \
    -v $(pwd):/app -w /app your-image:tag ./start-script.sh

If the container starts locally but not on Scalingo, the discrepancy likely lies in the platform’s environment (e.g., add‑on networking).

1. Contact support – provide the app name, the timestamp of the failed deployment, and the relevant log excerpts. Include the output of scalingo env (with secrets masked) and scalingo addons.

Rollback (when applicable)

Changing environment variables triggers a new deployment. If the new release introduces a regression, you can roll back to the previous release:

scalingo releases --app my-app   # list recent releases
scalingo releases:rollback v42   # replace v42 with the version you want to restore

Only perform a rollback after confirming that the earlier release was stable and that no data‑loss‑prone migrations were applied in the intervening release.