{"record":{"id":"e38671d1304a285a","repo":"clockworklabs/SpacetimeDB","slug":"port-is-already-in-use-please-free-up-the-port","errorCode":null,"errorMessage":"Port {} is already in use. Please free up the port or specify a different port with --listen-addr.","messagePattern":"Port (.+?) is already in use\\. 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":222,"sourceCode":"    worker_metrics::spawn_page_pool_stats(listen_addr.clone(), ctx.page_pool().clone());\n    worker_metrics::spawn_bsatn_rlb_pool_stats(listen_addr.clone(), ctx.bsatn_rlb_pool().clone());\n    let mut db_routes = DatabaseRoutes::default();\n    db_routes.root_post = db_routes.root_post.layer(DefaultBodyLimit::disable());\n    db_routes.db_put = db_routes.db_put.layer(DefaultBodyLimit::disable());\n    db_routes.pre_publish = db_routes.pre_publish.layer(DefaultBodyLimit::disable());\n    let extra = axum::Router::new().nest(\"/health\", spacetimedb_client_api::routes::health::router());\n    let task_dumps = TaskDumpRegistry::new([(\"main\", main_rt)]);\n    let service = router(&ctx, db_routes, IdentityRoutes::default(), extra)\n        .layer(Extension(task_dumps))\n        .with_state(ctx.clone());\n\n    // Check if the requested port is available on both IPv4 and IPv6.\n    // If not, offer to find an available port by incrementing (unless non-interactive).\n    let listen_addr = if let Some((host, port_str)) = listen_addr.rsplit_once(':') {\n        if let Ok(requested_port) = port_str.parse::<u16>() {\n            if !is_port_available(host, requested_port) {\n                if non_interactive {\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                // 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                            );","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/9e0d92412ff2248f401a8ad12d535f2b5ac30912/crates/standalone/src/subcommands/start.rs#L204-L240","documentation":"spacetime start checks the requested port on both IPv4 and IPv6 before binding. If the port is taken and the process runs in non-interactive mode, it cannot prompt for an alternative and bails immediately with this message.","triggerScenarios":"Starting the standalone server with --listen-addr on a port already bound by another process while non-interactive mode is active (no TTY or non-interactive flag), so is_port_available(host, port) returns false.","commonSituations":"A previous spacetime start still running in another terminal or as a background service; CI containers with an already-mapped port; another application (Postgres, node) occupying the default port.","solutions":["Free the port: find and stop the occupying process (lsof -i :<port> then kill, or stop the other spacetimedb instance).","Start on a different port: spacetime start --listen-addr 127.0.0.1:3001.","Run interactively so the server can offer to use a nearby free port."],"exampleFix":"# before\nspacetime start --listen-addr 127.0.0.1:3000 # port busy, non-interactive -> bail\n\n# after\nlsof -ti :3000 | xargs kill\nspacetime start --listen-addr 127.0.0.1:3000\n# or: spacetime start --listen-addr 127.0.0.1:3001","handlingStrategy":"validation","validationCode":"# probe the port before starting (checks availability):\nnc -z 127.0.0.1 3000 && echo \"busy -> pick another or free it\" || echo \"free\"\n# or: python3 -c \"import socket; socket.bind(('127.0.0.1',3000))\" && echo free","typeGuard":null,"tryCatchPattern":"match start_server(&args).await {\n    Err(e) if e.to_string().contains(\"already in use\") => {\n        // free the port (kill holder) or retry with --listen-addr on a new port\n    }\n    other => other,\n}","preventionTips":["Check for an already-running spacetimedb instance before starting another.","Pin an explicit --listen-addr in scripts and CI instead of relying on the default.","Add port-availability pre-checks to startup scripts."],"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"}