HumanSignal/label-studio · error · ConnectionError

\n* WARNING! *\n Could not find an available port\n to l

Error message

\n*** WARNING! ***\n Could not find an available port\n to launch label studio. \n Last tested port was {port}\n****************\n

What it means

When starting Label Studio via `label_studio.server.main`, the launcher probes ports starting from the configured/default port and increments up to 1000 times looking for a free one. If all 1000 candidate ports are occupied, a ConnectionError is raised so the user knows nothing could be bound.

Source

Thrown at label_studio/server.py:253


def check_port_in_use(host, port):
    logger.info('Checking if host & port is available :: ' + str(host) + ':' + str(port))
    host = host.replace('https://', '').replace('http://', '')
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        return s.connect_ex((host, port)) == 0


def _get_free_port(port, debug):
    # check port is busy
    if not debug:
        original_port = port
        # try up to 1000 new ports
        while check_port_in_use('localhost', port):
            old_port = port
            port = int(port) + 1
            if port - original_port >= 1000:
                raise ConnectionError(
                    '\n*** WARNING! ***\n Could not find an available port\n'
                    + ' to launch label studio. \n Last tested port was '
                    + str(port)
                    + '\n****************\n'
                )
            print(
                '\n*** WARNING! ***\n* Port '
                + str(old_port)
                + ' is in use.\n'
                + '* Trying to start at '
                + str(port)
                + '\n****************\n'
            )
    return port


def _project_exists(project_name):
    from projects.models import Project

View on GitHub (pinned to 0b49e9b539)

Solutions

Explicitly pass a known-free port: `label-studio start --port 9090`
Find and stop the process occupying the port: `lsof -i :8080` / `netstat -tlnp`
Restart the machine or clean up orphaned dev servers
Run inside a container/network namespace where fewer ports are consumed

Example fix

// before
label-studio
// after
label-studio --port 9090

Defensive patterns

Strategy: fallback

Validate before calling

const net = require('net');
function isPortFree(port) {
  return new Promise(resolve => {
    const s = net.createServer();
    s.once('error', () => resolve(false));
    s.once('listening', () => s.close(() => resolve(true)));
    s.listen(port, 'localhost');
  });
}
// pick a port before launching
let port = 8080; while (!(await isPortFree(port))) port++;

Type guard

function hasFreePort(candidate) { return typeof candidate === 'number' && candidate > 0 && candidate < 65536; }

Try / catch

try {
  await launchLabelStudio({ port });
} catch (e) {
  if (e instanceof ConnectionError && /Could not find an available port/.test(e.message)) {
    // free ports manually or restart host, then retry with an explicit --port
  } else throw e;
}

Prevention

Always pass an explicit --port in scripts, CI, and Docker
Monitor for orphaned dev servers and kill them (`lsof -i :8080`)
Run each instance in its own container or network namespace
Avoid ranges of concurrently started instances without port coordination

When it happens

Trigger: Running `label-studio` (main -> _get_free_port) with the default port on a machine where ports 8080..9080 (or configured port..+1000) are all in use; running many concurrent Label Studio instances; a service squatting a wide port range.

Common situations: Docker/K8s containers with another process holding 8080; CI machines running parallel jobs; LEFT-OPEN dev servers accumulating over time; corporate services bound to large port ranges.

Related errors

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/573e4ce2107d4d18. Report an issue: GitHub.