Skip to content

feat(docs): add troubleshooting guide for common application issues #3485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sc-zenokerr wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(docs): add troubleshooting guide for common application issues #3485

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions src/_posts/platform/app/2000-01-01-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Troubleshooting Your Application
modified_at: 2025-12-31 00:00:00
tags: troubleshooting errors crash deployment
index: 15
---

This page provides a summary of common issues you might encounter while deploying or running your application on Scalingo, along with links to more detailed guides.

## Deployment Issues

Deployment issues usually happen during the build phase, before your application is even started.

* **Unknown Technology**: Occurs when Scalingo cannot detect the programming language or framework of your application.
* **Image Too Large**: Your application image exceeds the 1.5 GiB limit.
* **Archive Too Large**: The source code archive (uncompressed) exceeds the 300 MB limit.

For more details on how to fix these, see our [Common Deployment Errors]({% post_url platform/getting-started/2000-01-01-common-deployment-errors %}) page.

## Boot and Startup Errors

These errors occur when the platform tries to start your application's containers.

* **Start Errors**: Generic errors during the startup process, often due to misconfiguration.
* **Timeout Errors**: Your application failed to bind to the assigned `PORT` within 60 seconds.
* **Hook Errors**: Failure of a `postdeploy` hook script.

Detailed information and fixes can be found in the [Application Crash]({% post_url platform/app/2000-01-01-crash %}#understanding-boot-errors) documentation.

## Runtime Issues

Runtime issues happen while your application is already running.

* **Application Crashes**: Unexpected termination of your application process.
* **5xx Errors**: Server-side errors that might be related to application crashes or timeouts.

Learn how to diagnose and recover from these in the [Application Crash]({% post_url platform/app/2000-01-01-crash %}#understanding-runtime-errors) section.

## Other Common Problems

* **SSH Connectivity**: Issues when trying to access your containers via SSH or pushing code. See [Troubleshooting SSH]({% post_url platform/getting-started/2000-01-01-troubleshooting-ssh %}).
* **Custom Error Pages**: If you want to customize the 502, 503, or 504 error pages displayed to your users, refer to [Custom Error and Maintenance Pages]({% post_url platform/app/2000-01-01-custom-error-page %}).