From c8a3d34280ab9c63bdcb6f7d7648e5ab27d306a6 Mon Sep 17 00:00:00 2001 From: Kemi-Elizabeth <97071326+Kemi-Elizabeth@users.noreply.github.com> Date: Thu, 27 Mar 2025 14:12:36 +0000 Subject: [PATCH] feat: revamped error section revamped error section with actionable points and additional solutions from devrel --- sites/upsun/.yaml | 3 + sites/upsun/src/development/troubleshoot.md | 89 ++++++++++++++++----- 2 files changed, 72 insertions(+), 20 deletions(-) diff --git a/sites/upsun/.yaml b/sites/upsun/.yaml index 608bcb8777..2d495da12a 100644 --- a/sites/upsun/.yaml +++ b/sites/upsun/.yaml @@ -171,6 +171,7 @@ elixir: - '1.10' - '1.9' supported: + - '1.18' - '1.15' - '1.14' legacy: @@ -702,6 +703,7 @@ postgresql: - '9.4' - '9.3' supported: + - '17' - '16' - '15' - '14' @@ -720,6 +722,7 @@ postgresql: - '11' - '10' supported: + - '17' - '16' - '15' - '14' diff --git a/sites/upsun/src/development/troubleshoot.md b/sites/upsun/src/development/troubleshoot.md index 245a79befc..1c902a613a 100644 --- a/sites/upsun/src/development/troubleshoot.md +++ b/sites/upsun/src/development/troubleshoot.md @@ -118,26 +118,75 @@ If you are using SSH, see how to [troubleshoot SSH access](../development/ssh/tr ## HTTP responses 502 Bad Gateway or 503 Service Unavailable -If you see these errors when accessing your application, -it indicates your application is crashing or unavailable. - -Typical causes and potential solutions include: - -- Your app is listening at the wrong place. - - Check your app's [upstream properties](/create-apps/app-reference/single-runtime-image.md#upstream). - - If your app listening at a port, make sure it's using the [`PORT` environment variable](/development/variables/use-variables.md#use-provided-variables). -- Your `{{< vendor/configfile "app" >}}` configuration has an error and a process isn't starting - or requests can't be forwarded to it correctly. - - Check your `web.commands.start` entry or your `passthru` configuration. -- The amount of traffic coming to your site exceeds the processing power of your application. - - You may want to [check if bots are overwhelming your site](https://support.platform.sh/hc/en-us/community/posts/16439634723858). -- Certain code paths in your application are too slow and timing out. - - Check your code is running smoothly. - - Consider using the [observability solution](../increase-observability/application-metrics/_index.md) included in your project to get a better view of your application. -- A PHP process is crashing because of a segmentation fault. - - See [how to deal with crashed processes](../languages/php/troubleshoot.md#troubleshoot-a-crashed-php-process). -- A PHP process is killed by the kernel out-of-memory killer. - - See [how to deal with killed processes](../languages/php/troubleshoot.md#troubleshoot-a-killed-php-process). +If you encounter a **502 Bad Gateway** or **503 Service Unavailable** error while accessing your application, it typically indicates that your application is either crashing or unavailable. Below are the typical causes and potential solutions: + +#### 1. Your app is listening at the wrong place +- **Solution**: Check your app's [upstream properties](/create-apps/app-reference/single-runtime-image.md#upstream). +- If your app is listening at a specific port, verify that it’s using the [`PORT` environment variable](/development/variables/use-variables.md#use-provided-variables) and ensure that it is listening at the correct port. + +#### 2. Configuration issues in `.upsun/config.yaml` +- **Solution**: Review your `.upsun/config.yaml` configuration. +- Look for any errors that might prevent a process from starting or cause issues with requests being forwarded properly. +- Check the `web.commands.start` entry or your `passthru` configuration for any misconfigurations. + +#### 3. Excessive traffic to your application +- **Solution**: Check if the amount of traffic coming to your site exceeds your application's processing power. +- Consider whether [bots or automated traffic might be overwhelming your site](https://support.platform.sh/hc/en-us/community/posts/16439634723858). + +#### 4. Slow code paths causing timeouts +- **Solution**: Check your application's code to ensure it is running efficiently. +- Use [observability tools](/increase-observability/application-metrics/_index.md) provided in your project for better insight into performance issues and potential bottlenecks. + +#### 5. PHP process crashing due to segmentation fault +If your PHP process crashes due to a segmentation fault, you may encounter a message like the warning error detailed below. This indicates that either a PHP extension is causing the segmentation fault or there’s an issue in your PHP app code. + +```text {location="/var/log/app.log"} +WARNING: [pool web] child 112 exited on signal 11 (SIGSEGV) after 7.405936 seconds from start +``` +- **Solution**: Review recent changes made to your app to identify potential causes. +- Consider using a debugging tool such as [Xdebug](/languages/php/xdebug.md) to help with quicker troubleshooting and identify the root cause of the crash. + +#### 6. PHP process killed by kernel out-of-memory killer +If your PHP process is killed by the kernel, you may encounter a message like the warning error detailed below. This indicates that the memory usage of your container exceeded the allocated limit, causing the kernel to kill the offending process. + +```text {location="/var/log/app.log"} +WARNING: [pool web] child 429 exited on signal 9 (SIGKILL) after 50.938617 seconds from start +``` +- **Solution**: Check if the memory usage of your app is as expected and try to optimize it. +- Use [sizing hints](/languages/php/fpm.md) to reduce the number of PHP workers, which will help lower the memory footprint. +- Add [additional resources](/manage-resources.md) using the `upsun resources:set` command to allocate more memory. + +{{< note >}} + +For more troubleshooting tips specifically for PHP, please head to the [PHP troubleshoot page](/languages/php/troubleshoot.md). + +{{< /note >}} + +#### 7. Project created but not pushed +- **Solution**: If a project is created but hasn’t been pushed, it can result in a 502 error. +- Ensure that the project is properly pushed to the environment. + +#### 8. Domain added to edge hostname but not the project +If you add a domain and point it to an edge hostname but haven’t added the domain to the project, it may cause a 502 error. Note that DNS services may catch this issue and provide their own 502 page. + +**Solution**: If you have added a domain, ensure that you have added the domain to the projectand also make sure that it is pointing to the correct edge hostname. + +#### 9. Mistyped edge hostname +If there’s a typo in the edge hostname or if you attempt to request a site while it’s still coming up, you may encounter a 502 error like the one detailed in the example below. It will specify that there is no route known for the url you have provided. + + - Example: + ```bash + url=https://pr-662-mendzpy-4wqljznn6rjno.ca-1.platformsh.site/ + response=$(curl -s -o /dev/null -I -X GET -w "%{http_code}" ${ALLOW_INSECURE:+--insecure} "${url//http:/https:}") + Error: Response from environment was something other than 200. Response returned was 502 + ``` + +- **Solution**: Review your edge hostname to ensure that it has been typed correctly. Also, ensure that your site has fully loaded up before requesting it. + +#### 10. `command.start` is failing +If the `command.start` entry is failing, it can result in a 502 error. + +- **Solution**: Comment out the `command:` and `start` lines in your `config.yaml`, then deploy. After deployment, SSH into the environment and copy-paste the command into the terminal to retrieve logs for further debugging. ## Site outage