Troubleshoot and clean up Ruby on Rails
Diagnose a failed checkpoint
Commit Gemfile.lock with a Linux platform entry (bundle lock --add-platform x86_64-linux). A missing SECRET_KEY_BASE is fixed by the linked Rails secret. MariaDB uses Trilogy; do not replace its connection scheme with an arbitrary string. The API-only app does not need an asset compilation step.
| 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 rails
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rails
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 rails → 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 rails
paas dbs list -o "$TUTORIAL_ORG" -p examples -e rails
paas envs delete rails -o "$TUTORIAL_ORG" -p examples --confirm rails
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.