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
Copy link
Contributor

@Frzk Frzk Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit puzzled with this PR because we already have this page: https://doc.scalingo.com/platform/app/crash and they seem to overlap a lot.

Maybe we should rather edit the existing one with missing information (if any)?
Maybe we should rename the existing one for it to be more discoverable?

Copy link
Contributor Author

@sc-zenokerr sc-zenokerr Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this new page is quite useful. It is common troubleshooting with links to other appropriate places. The motivation for the PR is provided in the issue, which is to help our customers find the information and reduce the load on support. @mickael-plassard @CalianasJ WDYT?

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 %}).