Need help troubleshooting? Reach out to us on Discord (opens in a new tab) or email.

Debugging Backend Statuses

Why did TimedOutBeforeReady occur?

TimedOutBeforeReady means that the server in the session backend did not start listening on port 8080 within 30 seconds of starting. This issue typically appears in two scenarios:

  • Your server is not running on port 8080. If you are using a server framework, you may need to configure it to run on port 8080. You may be able to specify this in the run command in your Dockerfile or in your server code. Check the docs for your particular framework on how to run on port 8080.
  • Your server is not bound to the local IP If you are using a server framework, you may need to configure its host to be (not localhost).
  • Your session backend takes longer than 30 seconds to start a server.
  • You don't have a server running in the session backend.

Why did my backend fail with an ErrorStarting status?

An ErrorStarting status usually means one of two things:

  1. Docker was unable to start your container because the image wasn't built for the linux/amd64 platform. When using npx jamsocket push to upload your image to Jamsocket, make sure that you are either using the --dockerfile flag (in which case, the CLI will build the image for you), or that you are pushing an existing image that was built for the x86 arch, i.e. docker build --platform=linux/amd64 ....
  2. The backend started but exited before reaching a Ready status. A backend is marked Ready when it starts a server on port 8080. You can view your backend logs to investigate the cause.

Why did my backend fail with a Failed status?

The backend exited on its own with a non-zero status. There are two likely scenarios:

  • Your backend was killed for hitting a memory limit. Refer to the backend's page (ie.[BACKEND NAME]) on the Jamsocket dashboard to see your memory usage. Contact us to upgrade your Jamsocket plan, if you'd like.
  • Your backend code hit an error while running. View your backend logs to investigate the cause.

Why did my backend stop with Lost status?

This error can occur if there was an outage caused by issues from our cloud provider or Jamsocket itself. Refer to our Jamsocket status page (opens in a new tab) to check for a possible outage. Contact us if the issue persists.

Why did my backend exit with Exited status?

The backend exited on its own with a zero status. Likely, you've exited the process or stopped the server.

Viewing Backend Logs

In production

In production, you can view your backend logs by running npx jamsocket logs BACKEND_NAME using the CLI.

In local development with the Dev CLI, the logs will be written to the Terminal. If you aren't seeing the appropriate program logs, compare the logs outputted in Docker using:

docker container ls -l
docker logs CONTAINER_ID

Debugging Docker

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

There may two reasons why this error occurs when running npx jamsocket push or npx jamsocket dev:

  • Docker is not running on your machine. Start Docker (ie. open Docker Desktop) and use docker ps to check that Docker is running.
  • You may need to check Enable default Docker socket under the Advanced tab in the Docker Desktop settings page.

Debugging Jamsocket API Errors

The backend spawned is not running my most recent image or NoSuchImage Error when spawning.

This error may occur when there is a mismatch between the image tag that an image was pushed with and the image tag that is used to spawn the backend.

  • If you push an image with a custom tag, you must also provide that tag at spawn time via the CLI or HTTP API. If the custom tag was not provided at spawn time, Jamsocket will look for an image with the tag latest. If there is no image with a latest tag, Jamsocket will return a NoSuchImage error.
  • If you push an image without a custom tag, Jamsocket gives that image the tag latest.

Receiving a failed connection or redirect error

When spawning a backend, the URL to connect to that backend contains an Auth Token.


Some frameworks may strip the Auth Token from spawn result URL used to connect to the session backend. Often times, this occurs when the framework is attempting a redirect. The side effect of this issue is a potential CORS error that looks like this: Access to fetch at 'http://localhost:9090/example-route' (redirected from 'http://localhost:9090/yK3en1rk87XyblPrFS7TV-JeWKhQ2k_XLYNeneElCYI/example-route/') from origin 'http://localhost:3000' has been blocked by CORS policy

Stripping the Auth Token will result in a failed connection to the session backend, because the Auth Token tells Jamsocket which session backend to route traffic to. Treat the connection token like a bearer token, because any client that knows it can access the backend.

Jamsocket is built by Drifting in Space.