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

_config.yml

@@ -59,7 +59,7 @@ highlighted:
     - /tools/cli/start
     - /platform/app/log-drain
     - /platform/deployment/deployment-process
-    - /platform/getting-started/common-deployment-errors
+    - /platform/getting-started/quick-resolution-guide
     - /languages/nodejs/start
     - /languages/php/start
     - /databases/postgresql/about/overview

redirections.yml

@@ -753,6 +753,12 @@
   - old: "/languages/nodejs/2000-01-01-angularjs"
     new: "/languages/nodejs/2000-01-01-angular"
 
+  - old: "/platform/app/crash"
+    new: "/platform/app/troubleshooting/overview"
+
+  - old: "/platform/getting-started/common-deployment-errors"
+    new: "/platform/getting-started/quick-resolution-guide"
+
 obsolete:
   - "/how-to-migrate-from-cloudcontrol/"
   - "/how-to-migrate-from-shelly-cloud/"

src/_posts/platform/app/2000-01-01-app-manifest.md

@@ -10,7 +10,7 @@ platform/app/2000-01-01-review-apps %}) and [one-click deploy button]({%
 post_url platform/deployment/2000-01-01-one-click-deploy %}). Its intent is to
 configure how an application should be created.
 
-If your application code is in a subdirectory configured through the [`PROJECT_DIR`]({% post_url platform/getting-started/2000-01-01-common-deployment-errors %}#project-in-a-subdirectory) environment variable, Scalingo detects the JSON manifest under this subdirectory. If there is no JSON manifest in the `PROJECT_DIR` folder, Scalingo tries to get the `scalingo.json` in every folder up to the root of your repository.
+If your application code is in a subdirectory configured through the [`PROJECT_DIR`]({% post_url platform/getting-started/2000-01-01-quick-resolution-guide %}#project-in-a-subdirectory) environment variable, Scalingo detects the JSON manifest under this subdirectory. If there is no JSON manifest in the `PROJECT_DIR` folder, Scalingo tries to get the `scalingo.json` in every folder up to the root of your repository.
 
 ## Configuration of the Environment
 

src/_posts/platform/app/2000-01-01-postdeploy-hook.md

@@ -30,10 +30,9 @@ happen in the following order:
 
 1. The application is built
 2. Containers from the new version of the application are started
-3. We wait until they started successfully (see common [deployment start
-   errors]({% post_url
-   platform/getting-started/2000-01-01-common-deployment-errors
-   %}#start-errors)). They are not reachable yet, see [limits](#limits) below.
+3. We wait until they started successfully (see [Boot and Startup Errors]({%
+   post_url platform/app/troubleshooting/2000-01-01-boot-and-startup-errors
+   %})). They are not reachable yet, see [limits](#limits) below.
 4. An extra container is started to run the `postdeploy` command
 5. If the `postdeploy` command succeeds, we update the routing
    configuration. The new containers start to get requests and the deployment is

src/_posts/platform/app/2000-01-01-procfile.md

@@ -118,7 +118,7 @@ uses the YAML syntax, there is **no extension**: no `.txt`, no `.yaml`, no
 `.yml`. **Only `Procfile`**.
 
 The file MUST live in your application's root directory or in `$PROJECT_DIR`,
-if your [application code lies in a subdirectory of your repository]({% post_url platform/getting-started/2000-01-01-common-deployment-errors %}#project-in-a-subdirectory).
+if your [application code lies in a subdirectory of your repository]({% post_url platform/getting-started/2000-01-01-quick-resolution-guide %}#project-in-a-subdirectory).
 
 ### Defining a Process Type
 
@@ -249,4 +249,3 @@ worker: bin/project -worker
 As you can see, `foreman` started a container for each process type defined in
 the project's Procfile (one for the `web` process type and another one for the
 `worker` process type).
-

src/_posts/platform/app/2000-01-01-troubleshooting.md

@@ -0,0 +1,3 @@
+---
+index: 12
+---

src/_posts/platform/app/troubleshooting/2000-01-01-boot-and-startup-errors.md

@@ -0,0 +1,94 @@
+---
+title: Boot and Startup Errors
+modified_at: 2026-04-10 00:00:00
+tags: troubleshooting crash startup boot timeout hook
+index: 3
+---
+
+Boot and Startup Errors occur when the platform tries to start your application's containers, before they reach the *running* state.
+
+For a broader overview, see [Troubleshooting Your Application]({% post_url platform/app/2000-01-01-troubleshooting %}). If the deployment fails before the containers are started, see [Deployment Issues]({% post_url platform/app/troubleshooting/2000-01-01-deployment-issues %}). If your application starts successfully and fails later, see [Runtime Issues]({% post_url platform/app/troubleshooting/2000-01-01-runtime-issues %}).
+
+There are 3 kinds of Boot and Startup Errors:
+[Start Errors](#understanding-start-errors),
+[Timeout Errors](#understanding-timeout-errors) and
+[Hook Errors](#understanding-hook-errors).
+
+## Understanding Start Errors
+
+The **Start Error** is the default kind of Boot Error. It is thrown as soon as
+an unmanaged error is detected and caught by the platform. It can occur at any
+moment, as long as your app isn't *running* yet.
+
+A Start Error makes the deployment fail instantly. Note that the former version
+of your application (if any), keeps running.
+
+In most cases, a Start Error is caused by a misconfiguration of your
+application, or by some unmanaged error/exception in your application's code.
+
+### Fixing Start Errors
+
+It's very likely that an action on your side is required to fix the issue. The
+deployment logs should help you identify the issue.
+
+## Understanding Timeout Errors
+
+When your application has a [`web` or a `tcp` process type]({% post_url platform/app/2000-01-01-procfile %}#special-process-types),
+the process started in the corresponding container(s) **MUST** bind to the
+provided network port (`PORT` environment variable) within a delay of 60
+seconds. After this deadline, the platform considers the application has being
+unreachable and throws a **Timeout Error**, causing the deployment to fail.
+
+- If this situation arises after a restart or a scale operation, the platform
+  automatically retries to start your container(s). After 20 unsuccessful
+  attempts (with an exponential backoff strategy), the platform gives up.
+  Note that your existing containers keep running during this time and after.
+
+- If you are trying to deploy a new version of an already running application,
+  this new deployment is considered a failure but the previous version of your
+  application keeps running.
+
+- Conversely, if this is a very first deployment, the platform does not make
+  any attempt to recover from the error. The deployment fails with a
+  **timeout-error** status, letting you know that your application didn't
+  bind to `PORT` soon enough.
+
+{% note %}
+  A Timeout Error can only occur if you have a `web` or a `tcp` process type,
+  which is very likely.
+{% endnote %}
+
+### Fixing Timeout Errors
+
+To fix a Timeout Error, make sure:
+- to bind to the provided network port, by using the `PORT` environment
+  variable.
+- to listen on `0.0.0.0` and not on `127.0.0.1`.
+- that your application is starting quickly enough.
+
+You may need to edit your
+[Procfile]({% post_url platform/app/2000-01-01-procfile %}) to fulfill these
+requirements.
+
+If your application doesn't need a `web` or `tcp` process type, make sure to
+[scale the unnecessary process type to zero]({% post_url platform/app/2000-01-01-web-less-app %}#deploy-a-web-less-application).
+
+## Understanding Hook Errors
+
+If your application has a [`postdeploy` process type]({% post_url platform/app/2000-01-01-procfile %}#special-process-types),
+the platform can throw a **Hook Error** if the post-deployment process fails.
+
+- In such a case, the deployment fails with a **hook-error** status.
+- If your application is already running, its code isn't updated and the former
+  version keeps running.
+
+{% note %}
+  Hook Errors can only occur if you have a `postdeploy` process type.
+{% endnote %}
+
+### Fixing Hook Errors
+
+Hook Errors are generally caused by an error in your codebase or by some
+misconfiguration. To recover from it, we first advise to investigate the logs
+of your application to understand the root cause. After fixing it, trigger a
+new deployment by pushing your updated code to Scalingo.

src/_posts/platform/app/troubleshooting/2000-01-01-deployment-issues.md

@@ -0,0 +1,190 @@
+---
+title: Deployment Issues
+modified_at: 2026-04-10 00:00:00
+tags: troubleshooting deployment buildpack build archive image
+index: 2
+---
+
+Deployment Issues happen during the build and packaging phase, before your
+application's containers are started.
+
+For a broader overview, see [Troubleshooting Your Application]({% post_url
+platform/app/2000-01-01-troubleshooting %}). If your application image is
+built successfully but the application fails to start, see [Boot and Startup
+Errors]({% post_url
+platform/app/troubleshooting/2000-01-01-boot-and-startup-errors %}).
+
+## Unknown Technology {#unknown-technology}
+
+When pushing your app to Scalingo, you might get the following error:
+
+```text
+<-- Start deployment of [my-app] -->
+ !     We didn't find the type of technology your are using...
+       We're sorry this build is failing!
+
+       Refer to the documentation to find out why:
+       https://doc.scalingo.com/deployment/unknown-technology
+
+       If you can't find the issue in your application,
+       please send us an email at support@scalingo.com
+
+       <3,
+       Scalingo
+ !   Error deploying the application
+ !   → Invalid return code from buildpack
+```
+
+There are two main causes for this problem: the application code is not at the
+root of the repository, or the expected detection files are missing.
+
+### Project in a Subdirectory {#project-in-a-subdirectory}
+
+It may happen that your project is in a subfolder of your Git repository. This
+is supported, but Scalingo's deployment system looks at the root of the Git
+repository by default.
+
+You need to set the `PROJECT_DIR` environment variable for your application,
+and our build system will automatically look at it. The variable has to target
+a valid directory, otherwise the deployment process will fail.
+
+**Example**
+
+If your project has the following architecture:
+
+```text
+/server
+/server/server.go
+/server/public/img/logo.png
+/server/public/css/style.css
+/server/public/js/app.js
+/doc
+/doc/api.md
+```
+
+You want to deploy what is in the `/server` directory, so you have to define
+`PROJECT_DIR=server`.
+
+{% warning %}
+Only the `PROJECT_DIR` directory will be present during runtime. The parent
+directory is not added to the application image we are building during the
+deployment phase.
+{% endwarning %}
+
+### Technology Detection
+
+To detect the technology used by your application, we iterate over the
+technologies alphabetically. If your project contains multiple technologies, we
+will pick the first one detected.
+
+If you want to skip the detection phase and force the use of a specific
+buildpack, add the environment variable `BUILDPACK_NAME` to your project.
+
+If you need to use multiple technologies, you can use the
+[multi-buildpacks]({% post_url platform/deployment/buildpacks/2000-01-01-multi %}).
+
+You can also develop your own buildpack and add the environment variable
+`BUILDPACK_URL` to have complete control on the detection and build phases.
+
+More information is available on [buildpacks]({% post_url
+platform/deployment/buildpacks/2000-01-01-intro %}) or
+[multi-buildpacks]({% post_url
+platform/deployment/buildpacks/2000-01-01-multi %}).
+
+Here is how we detect your technology:
+
+| Technology | Detection |
+| --- | --- |
+| [Ruby]({% post_url languages/ruby/2000-01-01-start %}) | A `Gemfile` should be present at the root of your repository. |
+| [Node.js]({% post_url languages/nodejs/2000-01-01-start %}) | The file `package.json` should be present at the root of the project. |
+| [Meteor]({% post_url languages/meteorjs/2000-01-01-start %}) | The directory `.meteor` should be present at the root of your project. |
+| [PHP]({% post_url languages/php/2000-01-01-start %}) | You need either an `index.php` file or both `composer.json` and `composer.lock` at the root of your project. |
+| [Python]({% post_url languages/python/2000-01-01-start %}) | The file `Pipfile`, `requirements.txt` or `setup.py` must be present at the root of your project. |
+| [Java]({% post_url languages/java/2000-01-01-start %}) | The file `pom.xml` should be present at the root of your project. |
+| [Scala]({% post_url languages/scala/2000-01-01-start %}) | You need at least an `*.sbt` file, a `project/*.scala` file, a `.sbt/*.scala` file, or a `project/build.properties` file. |
+| [Groovy]({% post_url languages/groovy/2000-01-01-start %}) | The `grails-app` directory must be at the root of your project. |
+| [Clojure]({% post_url languages/clojure/2000-01-01-start %}) | The file `project.clj` must be at the root of your project. |
+| [Go]({% post_url languages/go/2000-01-01-start %}) | You need at least one `*.go` file at the root of your project. |
+| [Crystal]({% post_url languages/crystal/2000-01-01-start %}) | The file `shard.yml` should be present at the root of your project. |
+| [Elixir]({% post_url languages/elixir/2000-01-01-start %}) | Create a `.buildpacks` file at the root of your project to declare the Elixir buildpack explicitly. |
+
+## Git Submodule {#git-submodule}
+
+If your project repository uses Git submodules, please be aware that Scalingo
+will not pull them. This Git feature is not supported on the platform for
+different reasons. The main reason is that we currently have no way to
+authenticate the `git pull` operation to a private Git repository during the
+deployment.
+
+We recommend vendoring a specific release of the code of the sub-repository in
+your main repository before pushing.
+
+## Build Errors {#build-errors}
+
+When your application is deployed, the dependencies are gathered and packaged
+into an application image.
+
+### Invalid Return Code From Buildpack
+
+Your application image is built using a buildpack ([list of buildpacks]({%
+post_url platform/deployment/buildpacks/2000-01-01-intro %})). If the
+buildpack exits with an error, it is probably linked to your project. You
+should be able to see the content of the error in your console, then adapt your
+code or configuration accordingly.
+
+If you think the error comes from our buildpacks, contact us and we will
+investigate it.
+
+### Image Too Large
+
+The maximal size of an application image is **2 GiB**. If your assets, your
+dependencies and your code weigh more than this limit, different solutions are
+available to lighten the image of your application:
+
+* Try to remove unused external dependencies or assets.
+* Define a [.slugignore file]({% post_url platform/app/2000-01-01-slugignore %})
+  to exclude files from the image.
+
+If you absolutely need all these data, please contact us at
+[support@scalingo.com](mailto:support@scalingo.com).
+
+{% note %}
+Why this quota? Besides being a security limit, this quota is also present to
+preserve the PaaS user experience. A large image results in longer deployments,
+and the instantness aspect is lost.
+{% endnote %}
+
+### Archive Too Large
+
+When deploying an application, the Scalingo build system downloads the source
+code as an archive. The maximum archive size is limited to **300 MB**.
+
+If your archive exceeds this limit you will get the following error:
+
+```text
+Fail to fetch source code: fail to handle tgz: The archive is too heavy (more than 314572800 bytes)
+```
+
+{% note %}
+The limit applies to the **uncompressed** archive.
+
+For example: given a **200 MB `.tar.gz`** archive, when the underlying `.tar`
+archive is larger than **300 MB**, then you will encounter this limit.
+{% endnote %}
+
+If you need to deploy a larger archive, please contact us at
+[support@scalingo.com](mailto:support@scalingo.com).
+
+## Not Sure This Is Your Case?
+
+If the build succeeded and the platform is now trying to start your
+application, continue with [Boot and Startup Errors]({% post_url
+platform/app/troubleshooting/2000-01-01-boot-and-startup-errors %}).
+
+If your issue looks specific to a given language or framework, check the
+technology-specific guides such as [Node.js Common Deployment Errors]({%
+post_url languages/nodejs/2000-01-01-deployment-errors %}).
+
+If the problem is related to process types, start commands, or the command used
+to boot your application, review the [Procfile]({% post_url
+platform/app/2000-01-01-procfile %}) documentation.

src/_posts/platform/app/troubleshooting/2000-01-01-overview.md

@@ -0,0 +1,46 @@
+---
+title: Troubleshooting Your Application
+modified_at: 2026-04-10 00:00:00
+tags: troubleshooting errors crash deployment
+index: 1
+---
+
+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 and packaging phase, before
+your application's containers are started.
+
+* **Unknown Technology**: Occurs when Scalingo cannot detect the programming language or framework of your application.
+* **Project in a Subdirectory**: Scalingo looks at the root of the repository unless `PROJECT_DIR` is configured.
+* **Buildpack Failure**: The buildpack exits with an error while preparing the application image.
+* **Image Too Large**: Your application image exceeds the 2 GiB limit.
+* **Archive Too Large**: The source code archive (uncompressed) exceeds the 300 MB limit.
+
+For more details on how to fix these, see [Deployment Issues]({% post_url
+platform/app/troubleshooting/2000-01-01-deployment-issues %}).
+
+## 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 [Boot and Startup Errors]({% post_url platform/app/troubleshooting/2000-01-01-boot-and-startup-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 [Runtime Issues]({% post_url platform/app/troubleshooting/2000-01-01-runtime-issues %}) guide.
+
+## 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 %}).