Port {} is already in use and could not find an available po

Error message

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.

What it means

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.

Source

Thrown at crates/standalone/src/subcommands/start.rs:244

                }
                // Port is in use, try to find an alternative
                match find_available_port(host, requested_port.saturating_add(1), 100) {
                    Some(available_port) => {
                        let question = format!(
                            "Port {} is already in use. Would you like to use port {} instead?",
                            requested_port, available_port
                        );
                        if prompt_yes_no(&question) {
                            format!("{}:{}", host, available_port)
                        } else {
                            anyhow::bail!(
                                "Port {} is already in use. Please free up the port or specify a different port with --listen-addr.",
                                requested_port
                            );
                        }
                    }
                    None => {
                        anyhow::bail!(
                            "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.",
                            requested_port
                        );
                    }
                }
            } else {
                listen_addr.to_string()
            }
        } else {
            listen_addr.to_string()
        }
    } else {
        listen_addr.to_string()
    };

    let tcp = TcpListener::bind(&listen_addr).await.context(format!(
        "failed to bind the SpacetimeDB server to '{listen_addr}', please check that the address is valid and not already in use"

View on GitHub (pinned to 9e0d92412f)

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.

Example fix

# before
spacetime start # port 3000 + next 100 all busy -> bail

# after
ss -ltnp | grep 300
spacetime start --listen-addr 127.0.0.1:3987

Defensive patterns

Strategy: fallback

Validate before calling

# scan a wide range for a free port before starting:
python3 - <<'EOF'
import socket
for p in range(3000, 4000):
    try:
        socket.bind(('127.0.0.1', p)); print(p); break
    except OSError: pass
EOF
# then: spacetime start --listen-addr 127.0.0.1:<found>

Try / catch

match start_server(&args).await {
    Err(e) if e.to_string().contains("could not find an available port") => {
        // pick a port from a distant free range explicitly and restart
    }
    other => other,
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Developer machines with long port runs consumed by containers/IDEs; CI runners with crowded port spaces; starting many instances in a loop.

Related errors

AI-assisted analysis of clockworklabs/SpacetimeDB@9e0d92412f (2026-08-20). Data as JSON: /api/errors/9a470e5fb75085fb. Report an issue: GitHub.