{"record":{"id":"9a470e5fb75085fb","repo":"clockworklabs/SpacetimeDB","slug":"port-is-already-in-use-and-could-not-find-an-av","errorCode":null,"errorMessage":"Port {} is already in use and could not find an available port nearby. Please free up the port or specify a different port with --listen-addr.","messagePattern":"Port (.+?) is already in use and could not find an available port nearby\\. Please free up the port or specify a different port with --listen-addr\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/standalone/src/subcommands/start.rs","lineNumber":244,"sourceCode":"                }\n                // Port is in use, try to find an alternative\n                match find_available_port(host, requested_port.saturating_add(1), 100) {\n                    Some(available_port) => {\n                        let question = format!(\n                            \"Port {} is already in use. Would you like to use port {} instead?\",\n                            requested_port, available_port\n                        );\n                        if prompt_yes_no(&question) {\n                            format!(\"{}:{}\", host, available_port)\n                        } else {\n                            anyhow::bail!(\n                                \"Port {} is already in use. Please free up the port or specify a different port with --listen-addr.\",\n                                requested_port\n                            );\n                        }\n                    }\n                    None => {\n                        anyhow::bail!(\n                            \"Port {} is already in use and could not find an available port nearby. \\\n                             Please free up the port or specify a different port with --listen-addr.\",\n                            requested_port\n                        );\n                    }\n                }\n            } else {\n                listen_addr.to_string()\n            }\n        } else {\n            listen_addr.to_string()\n        }\n    } else {\n        listen_addr.to_string()\n    };\n\n    let tcp = TcpListener::bind(&listen_addr).await.context(format!(\n        \"failed to bind the SpacetimeDB server to '{listen_addr}', please check that the address is valid and not already in use\"","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/9e0d92412ff2248f401a8ad12d535f2b5ac30912/crates/standalone/src/subcommands/start.rs#L226-L262","documentation":"When the requested port is busy in interactive mode, spacetime start searches upward from port+1 for at most 100 candidates (find_available_port). If none of those 100 ports is free, it gives up and bails with this stronger message.","triggerScenarios":"Interactive start where the requested port and the next 100 sequential ports are all occupied, e.g. a heavily used ephemeral range or many services bound consecutively.","commonSituations":"Developer machines with long port runs consumed by containers/IDEs; CI runners with crowded port spaces; starting many instances in a loop.","solutions":["Free the original port by stopping whatever holds it.","Specify a port in a clearly free range explicitly: spacetime start --listen-addr 127.0.0.1:<far-away-port>.","Inspect what occupies the range (ss -ltn / lsof -i) and prune unused listeners."],"exampleFix":"# before\nspacetime start # port 3000 + next 100 all busy -> bail\n\n# after\nss -ltnp | grep 300\nspacetime start --listen-addr 127.0.0.1:3987","handlingStrategy":"fallback","validationCode":"# scan a wide range for a free port before starting:\npython3 - <<'EOF'\nimport socket\nfor p in range(3000, 4000):\n    try:\n        socket.bind(('127.0.0.1', p)); print(p); break\n    except OSError: pass\nEOF\n# then: spacetime start --listen-addr 127.0.0.1:<found>","typeGuard":null,"tryCatchPattern":"match start_server(&args).await {\n    Err(e) if e.to_string().contains(\"could not find an available port\") => {\n        // pick a port from a distant free range explicitly and restart\n    }\n    other => other,\n}","preventionTips":["On crowded machines, allocate server ports from a dedicated high range.","Audit listeners (ss -ltnp) and prune idle services occupying port runs.","Wrap spacetime start in scripts that pre-select a verified-free port."],"tags":["standalone","server-start","port-conflict","networking"],"backgroundTag":"port-already-in-use","analyzedSha":"9e0d92412ff2248f401a8ad12d535f2b5ac30912","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}