Debugging

Below you will find common error scenarios and how to debug them.

Build process

Node GYP Errors

Node-gyp errors occur when native Node.js modules compiled for one system architecture don't match your current environment. This commonly happens with modules like Sharp, bcrypt, or sqlite3 when moving between different operating systems, CPU architectures (x86 vs ARM), or Node.js versions. On sherpa.sh your project is build inside an Alpine Linux container running on x86 architecture.

When native module installation fails during npm install, preventing your build from completing at all, using the install flag --ignore-scripts skips postinstall scripts that often handle native module compilation.

Then you can manually rebuild for your architecture with the npm rebuild command.

Example

# Failing build command
npm i

# Working build command
npm i --ignore-scripts && npm rebuild

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:

 RUN apk add --no-cache
    bash \
    curl \
    nodejs \
    npm \
    python3 \
    make \
    g++ \
    build-base \ 
    gcompat \
    linux-headers \
    openssl-dev \
    musl-dev \
    libc-dev \
    zlib-dev \
    pkgconfig \
    git

If you are in need of a package not listed above during the build process. Please let us know in discord and we will add it for you. Or you can append apk add [PACKAGE] && to your build command.

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

Framework/Tool	How to Disable ESLint During Build
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.

Runtime Errors

Module not found errors

This is typically due to missing binaries.

Next.js offers an optimized “standalone” output (by setting output: "standalone" in next.config.js) specifically for Docker/container deployments.

• The “standalone” build traces all runtime dependencies and bundles the minimal required Node modules and files for production runtime into .next/standalone.

• For a production Docker image, you only need to copy the content of .next/standalone, .next/static, and /public (and related assets) into a lightweight Node.js base image.

• System-level Ubuntu packages are usually not needed at runtime if everything was bundled and compiled during the build phase, unless your app directly uses OS libraries at runtime (which is rare for most web apps).

Url doesn't display your app

502 Error when visiting your application

This error means there is a bug in your application that is preventing it from starting. The first thing you should do is check your application logs in the dashboard.

1. First navigate to logs

1. Select your application and environment then click console logs to get the output from your application

From here you should see the message, and begin debugging. Good first steps are to copy your environment variables locally and try to replicate the issue on your local machine (make sure to use the same build and run commands you use in Sherpa.sh)

If you are deploying a docker project, please try building then running your docker container locally using this command (be sure to use the same Dockerfile you set in the Sherpa.sh portal):

docker build \
  --platform linux/amd64,linux/arm64 \
  --no-cache --pull --force-rm \
  --build-arg ENV_FILE=.env \
  --t local-test/my-project:latest \
  --load .

Make sure you have a .envfile in directory you run this command. This should contain the environment variables you have set for your application in the sherpa.sh dashboard.

Then running it using this command:

docker run --env-file .env local-test/my-project:latest

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.

1. You have the wrong DNS records set. If using a custom domain, check that you have properly routed your Custom Domain with the proper DNS records

2. 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.