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.

JNLP4 Connect Timeout / Javascript heap out of memory

This occurs when you're build project has run out of memory. The solution is to either reduce the memory used during your build process OR to upgrade to a dedicated build server.

Sentry Source Maps

Sentry source maps can consume a significant amount of memory, even for small to medium-sized projects. This can be problematic if upgrading to a dedicated build server is not feasible.

To mitigate this issue, you can disable source maps in production. In a Next.js application, you can achieve this by modifying your next.config.js:

module.exports = withSentryConfig{
  config,
  sourcemaps: {
      disable: true,
  },
};

By setting sourcemaps.disable to false, you prevent the generation of source maps in the build process, thereby reducing memory usage during the build process.

Failed to compute cache key during container build

The error message likely indicates that the directory specified for the output is incorrect or does not exist. In this case, "/baddir" is likely not the directory where your build command outputs files. The "failed to calculate checksum" part of the error means that the system cannot find this directory to proceed with the build. Make sure to verify and correct the output directory in your build settings.

ERROR: failed to build: failed to solve: failed to compute cache key: failed to calculate checksum of ref vxd2szn1mu5hcxp86ikag4uei::ia0osmeodh7hzb4n6p9iffjg9: "/baddir": not found
script returned exit code 1

ERROR! Directory does not exist

This typically occurs when building projects using SSG (Static Site Generation) and your project outputs to a different directory during build that what you have set for your output directory in the your build settings.

To debug this, run your build command locally and see where your folder is output to, and confirm that it matches the directory in your build settings.

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.

First navigate to logs

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.

This error occurs when the size of the request headers sent to the backend exceed the allowed limits. Specifically, individual request headers must not exceed 16 KB, and the combined size of all headers, including the header names, must not exceed 32 KB. This keeps memory resources effecient and your app serving request with low latency.

This issue often arises from excessively large headers in a request. On Sherpa.sh, applications may have custom headers, which, if overly large, can trigger this error during server request processing.

To troubleshoot this error, follow these steps:

Limit header size: Ensure that the size of each request header does not exceed 16 KB
Manage total header size: Monitor and control the combined size of all headers, keeping it under 32 KB
Review cookies: Since cookies are included in the header, it's crucial to limit their size as part of the overall header size

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.

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

PreviousPromotions & Rollbacks NextSecuring your Application

Last updated 7 days ago