Skip to content
LabTether

Quick Diagnostics

When something is off and you are not sure where to start, run through these first steps to narrow down the problem before diving into a specific troubleshooting page.

First steps

Start with a rapid health check of the hub itself. Everything in LabTether flows through the hub, so if it is unhealthy, everything downstream will look broken too.

1. Hub health endpoint

curl -s https://<hub-host>:8443/healthz

A healthy hub returns 200 OK. If this fails, the hub process or its database connection is the first thing to fix.

2. Docker service status

docker compose ps

Confirm all expected containers are running. Look for containers in a restart loop or exited state. If a container is restarting, check its logs with docker compose logs <service> --tail 50.

3. Network path

From a machine that should be able to reach the hub, verify basic connectivity:

# DNS resolves
dig +short <hub-hostname>

# Port is reachable
nc -zv <hub-host> 8443

If /healthz responds and Docker looks healthy, the hub is fine and the problem is somewhere more specific.

4. Automated baseline check

If you have a development checkout of the hub, run:

make setup-doctor

This validates environment prerequisites, database connectivity, and configuration consistency in one pass.

What kind of problem?

Use the table below to jump to the right page based on what you are seeing.

Symptom Go to
A node shows offline or won't reconnect Node Won't Connect
A connector test fails or sync returns errors Connector Sync Failures
Desktop session won't start, drops, or shows a black screen Desktop Session Issues
Terminal session won't start or stalls Terminal Session Issues
Can't log in, session expires immediately, SSO problems Login and Authentication Issues
Console feels slow, pages take a long time to load Slow UI and Performance

If the problem spans multiple categories -- for example, all nodes are offline and you also cannot log in -- start with the hub health checks above. A hub-level issue often explains multiple symptoms at once.

Tip: When you open a support thread or file an issue, include the output of /healthz, docker compose ps, and the relevant hub logs. This saves a round trip of back-and-forth.