Debugging
Below you will find common error scenarios and how to debug them.
Build process
Missing a dependency during install command
When a new deployment is triggered your project is built inside a docker container. This docker container is an alpine linux distribution with predefined packages installed. If you receive an error about a missing package during a build, it is likely because it is not included by default in our docker image. The following packages are installed by default:
ESLint errors during build command
If you have eslint enabled lint errors will cause a build to fail. You can either fix your linting errors then commit your changes or disable ESLint.
The method to disable ESLint during your build process depends on the framework or toolchain you are using. Here are some common approaches:
Summary Table
Create React App
Set DISABLE_ESLINT_PLUGIN=true in .env or script
Next.js
Set {eslint: {ignoreDuringBuilds: true}} in next.config.js
Other/Custom
Remove ESLint from build config or delete ESLint-related files.
Note: Disabling ESLint during builds is generally not recommended unless you have linting handled elsewhere as it may allow code quality issues to slip into production.
Url doesn't display your app
502 Error when visiting your application
You will receive a 502 error when you application fails to startup. This is common for Docker container deployments, where your container builds successfully but fails on your run command.
The first step is to check your logs in the sherpa.sh portal. Visit the Logs page then select your project and deployment. Once you've selected the offending deployment in the tab filters in the upper right select "Application Console". Here you will see the most recent logs from your application - which likely will contain the source of the error.
To debug locally, please try building and running your docker container locally using this command:
Then running it using this command:
If you project runs locally this way, it should work on sherpa.sh and you'll stop experiencing the 502 error.
500 Error when visiting your application
This is likely due to a bug in your app, or a misconfigured environment variable. The first step is to check your logs in the sherpa.sh portal. Visit the Logs page then select your project and deployment. Once you've selected the offending deployment in the tab filters in the upper right select "Application Console". Here you will see the most recent logs from your application - which likely will contain the source of the error.
Content issues after a successful deployment
Static assets get (blocked:csp) error
Your Content-Security-Policy on static assets is likely mapped only to self. Sherpa.sh uses a separate url for static assets to improve performance. Our deployment process typically overrides these settings. But if you have a custom setup in your projects, you will need to update the content security policy to allow all urls on your root domain.
SSL Certificate Issue.
If you have a cert issue, or receive net::ERR_CERT_COMMON_NAME_INVALID. There are usually one of two causes.
Your Cert didn't get picked up by the deployment. This can happen if you deploy before a cert is validated, while changing setting during deployment, and a few other cases. If this happens - redeploy your project and it will pick up your certificate.
If you still have issues. Please visit our Discord and open a ticket.
This site can't be reached. Server IP address could not be found.
While rare, this can happen to deployments that are in progress during an infrastructure upgrade. If you have this issue, redeploy your project and it will pick up the IP. If you still have issues after redeploying, please visit our Discord and open a ticket.
Last updated