{"record":{"id":"573e4ce2107d4d18","repo":"HumanSignal/label-studio","slug":"n-warning-n-could-not-find-an-available-p","errorCode":null,"errorMessage":"\\n*** WARNING! ***\\n Could not find an available port\\n to launch label studio. \\n Last tested port was {port}\\n****************\\n","messagePattern":"\\\\n\\*\\*\\* WARNING! \\*\\*\\*\\\\n Could not find an available port\\\\n to launch label studio\\. \\\\n Last tested port was (.+?)\\\\n\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\*\\\\n","errorType":"console","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"label_studio/server.py","lineNumber":253,"sourceCode":"\n\ndef check_port_in_use(host, port):\n    logger.info('Checking if host & port is available :: ' + str(host) + ':' + str(port))\n    host = host.replace('https://', '').replace('http://', '')\n    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n        return s.connect_ex((host, port)) == 0\n\n\ndef _get_free_port(port, debug):\n    # check port is busy\n    if not debug:\n        original_port = port\n        # try up to 1000 new ports\n        while check_port_in_use('localhost', port):\n            old_port = port\n            port = int(port) + 1\n            if port - original_port >= 1000:\n                raise ConnectionError(\n                    '\\n*** WARNING! ***\\n Could not find an available port\\n'\n                    + ' to launch label studio. \\n Last tested port was '\n                    + str(port)\n                    + '\\n****************\\n'\n                )\n            print(\n                '\\n*** WARNING! ***\\n* Port '\n                + str(old_port)\n                + ' is in use.\\n'\n                + '* Trying to start at '\n                + str(port)\n                + '\\n****************\\n'\n            )\n    return port\n\n\ndef _project_exists(project_name):\n    from projects.models import Project","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/HumanSignal/label-studio/blob/0b49e9b53917880baf1dd85d574fe5541a9aafb2/label_studio/server.py#L235-L271","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nlabel-studio\n// after\nlabel-studio --port 9090","handlingStrategy":"fallback","validationCode":"const net = require('net');\nfunction isPortFree(port) {\n  return new Promise(resolve => {\n    const s = net.createServer();\n    s.once('error', () => resolve(false));\n    s.once('listening', () => s.close(() => resolve(true)));\n    s.listen(port, 'localhost');\n  });\n}\n// pick a port before launching\nlet port = 8080; while (!(await isPortFree(port))) port++;","typeGuard":"function hasFreePort(candidate) { return typeof candidate === 'number' && candidate > 0 && candidate < 65536; }","tryCatchPattern":"try {\n  await launchLabelStudio({ port });\n} catch (e) {\n  if (e instanceof ConnectionError && /Could not find an available port/.test(e.message)) {\n    // free ports manually or restart host, then retry with an explicit --port\n  } else throw e;\n}","preventionTips":["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"],"tags":["network","port-in-use","server-startup","label-studio"],"backgroundTag":"port-already-in-use","analyzedSha":"0b49e9b53917880baf1dd85d574fe5541a9aafb2","analyzedAt":"2026-08-29T00:39:52.578Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}