Troubleshooting

Fix the common setup and runtime issues you can actually hit in SkyPort.

This page focuses on the failures that are realistic for the current codebase: missing binaries, bad server profiles, Docker permissions, and startup issues.

`skyport` is not found

terminal

which skyport
echo $PATH

Reinstall the binary into a directory that is already on PATH.
On Windows, restart the terminal after updating the environment variable.

`skyport start webui` cannot find the backend binary

The web UI launcher searches for skyport-server, skyport-backend, or a custom path passed through --binary.

terminal

skyport start webui --binary /usr/local/bin/skyport-server

If you are building from source, make sure the backend target exists under bin/server/.

Docker commands fail

terminal

docker info
ls -la /var/run/docker.sock

Start the Docker daemon.
Add your user to the docker group on Linux.
Make sure Docker Desktop is running on macOS or Windows.

The TUI says no active server profile

terminal

skyport server add --name local --url http://localhost:8080
skyport server list

Confirm the server URL is reachable.
Make sure the user account exists on that SkyPort instance.
Re-run skyport login after selecting the correct profile.

The UI opens but looks empty

Confirm the backend has a live database and metrics can be collected.
Check whether the host is running any containers, PM2 processes, or deployments yet.

WSL networking feels inconsistent

Use the address printed by skyport start webui instead of assuming localhost is always correct.
If Docker runs on Windows, keep WSL integration enabled.

Need more context

Open these pages when the issue is workflow-specific:

Edit this pageorReport an issue

First Deployment

Walk through a real SkyPort deployment flow from project to logs.

Dashboard

Overview of the SkyPort web dashboard and what it is meant to show.