Troubleshooting

Debugging Backend Terminations

Start-up timeout

If your backend has a terminated status with a startup_timeout “termination reason”, that means the server in the session backend did not start listening on port 8080 within 5 minutes 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 0.0.0.0. If you are using a server framework, you may need to configure its host to be 0.0.0.0 (not localhost).
• Your session backend takes longer than 5 minutes to start a server.
• You don’t have a server running in the session backend.

Backend terminated immediately after a starting status

If your backend was terminated immediately after a starting status, it may be because Docker was unable to start your container. This most often occurs 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 ....

Backend failed or exited on its own

If your backend did not encounter a terminating or hard-terminating status, it may be because your backend code exited or failed on its own. You can get more information about the backend on the Jamsocket Dashboard or by running npx jamsocket backend info [BACKEND_ID]. You can also view your backend logs to investigate the cause.

Backend hit a memory limit

If your backend terminated with the exit code 139, it was likely killed for hitting a memory limit. Refer to the backend’s page (ie. app.jamsocket.com/backend/[BACKEND_ID]) on the Jamsocket dashboard to see your memory usage. Contact us to upgrade your Jamsocket plan, if you’d like.

Backend’s termination_reason is lost

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 to check for a possible outage. Contact us if the issue persists.

Viewing Backend Logs

In production

In production, you can view your backend logs by running npx jamsocket logs BACKEND_ID 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.

Dev CLI appears to be hanging and isn’t starting a dev server.

This issue often occurs when Docker is running out of disk. Check if you’re running on space saver mode or if old containers must be cleared. To clear any old containers, you can run docker system prune -a.

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.

• By default, services are configured to spawn the most recent image with the tag latest. If you push an image with a custom tag, that image will not be used when spawning unless you (1) configure your service to use that image tag when spawning (see the use-image command), or (2) provide that tag at spawn time.
• 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.

http://localhost:9090/AUTH_TOKEN

Some frameworks may strip the Auth Token from the connection URL. 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.

Common Socket.IO Issues

Socket.IO treats the Jamsocket connection token as part of the room identifier.

If you call io('my-backend.com/my-connection-token'), Socket.IO will treat /my-connection-token as part of a room to connect to on the Socket.IO server.

To avoid this, the connection token should be removed from the connection url and used like so:

const url = new URL('https://my-backend.com/my-connection-token')
io(url.origin, { path: url.pathname })

Socket.IO tries to connect before session backend has a ready status

When you call io(), it will by default try to connect to the Jamsocket session backend even before the backend is ready. To address this issue, use the Jamsocket API or client library to check whether the backend is ready before calling io().

Using the Jamsocket HTTP API, you can check a backend’s status using the status stream API or by polling for the current status.

You can also use the Jamsocket Typescript library to get an onReady method.