Troubleshoot and clean up Node.js and Express
Diagnose a failed checkpoint
Commit package-lock.json and use npm ci locally. Keep Procfile and package.json in the source root. The worker mode is node app.mjs worker; npm start runs the web mode.
| Symptom | Check |
|---|---|
| No build starts | The Environment uses release source Build, the pushed branch is main, and both apps use the shared repository root. Review framework availability. |
| Build fails detection | Check the manifest and lockfiles in the committed source, not just local files. See the hello chapter’s file list. |
| Health check fails | Port is 3000, binding is 0.0.0.0, path is /health, and the web app selects web. |
| Notes returns 503 | Primary attachment is DATABASE_URL, engine matches its type, database is running, and the schema command printed Schema ready. |
| Export stays queued | Worker selects worker, has its own database and REDIS_URL attachments, and has one running replica. A recovered pending job waits up to 30 seconds. |
| Download fails after adding S3 | Attach the bucket to both apps with no prefix, wait for their restart, and create a new export. Old Redis-only exports have no S3 object. |
| Forbidden operation | Confirm your project capabilities for deploying, databases, storage, or secrets; ask the project administrator to grant the needed access. |
Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.
CLI:
paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs
Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.
Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.
Clean up
Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.
Dashboard: open Project Examples → Environment nodejs → Settings → Delete Environment,
then confirm its name. Make sure this Environment contains only the tutorial resources.
CLI: review its resources, then confirm deletion:
paas apps list -o "$TUTORIAL_ORG" -p examples -e nodejs
paas dbs list -o "$TUTORIAL_ORG" -p examples -e nodejs
paas envs delete nodejs -o "$TUTORIAL_ORG" -p examples --confirm nodejs
This removes the web/worker, primary and optional databases, Redis, and tutorial bucket
created in this Environment. If you used local services, run docker compose down -v
from the example folder to discard that separate local dataset.