tursodatabase/turso · error · anyhow::Error

local sync server on port {port} did not become ready within

Error message

local sync server on port {port} did not become ready within {READY_TIMEOUT:?}

What it means

Thrown by TursoServer::spawn in the bindings/rust sync tests when the spawned sync server process stays alive but never accepts connections on its port within READY_TIMEOUT (60 seconds). The readiness loop kills the child and returns this error from bindings/rust/src/sync.rs:1164. It means startup is slow or blocked, not that the port was taken (that branch retries instead).

Source

Thrown at bindings/rust/src/sync.rs:1261

                        }
                        match child
                            .try_wait()
                            .context("failed to poll local sync server")?
                        {
                            Some(status) => {
                                // Child exited (most likely the port was
                                // reserved or already taken): retry.
                                eprintln!(
                                    "local sync server on port {port} exited with {status} \
                                     before becoming ready (attempt {attempt}/{SPAWN_ATTEMPTS})"
                                );
                                break;
                            }
                            None => {
                                if started.elapsed() > READY_TIMEOUT {
                                    let _ = child.kill();
                                    let _ = child.wait();
                                    return Err(anyhow!(
                                        "local sync server on port {port} did not become ready \
                                         within {READY_TIMEOUT:?}"
                                    ));
                                }
                            }
                        }
                        sleep(Duration::from_millis(100));
                    }
                }
                Err(anyhow!(
                    "local sync server failed to start after {SPAWN_ATTEMPTS} attempts"
                ))
            }
        }

        pub fn db_url(&self) -> &str {
            &self.db_url
        }

View on GitHub (pinned to 492c4a71cd)

Solutions

Re-run the test first - slow starts are usually transient under load
Run the server binary manually with the same arguments to see where startup stalls
Lower test parallelism so startup finishes within the 60s budget
If reproducible, temporarily raise READY_TIMEOUT in bindings/rust/src/sync.rs to confirm it is timing, not a hang

Example fix

// bindings/rust/src/sync.rs - local diagnosis only
// before
const READY_TIMEOUT: Duration = Duration::from_secs(60);
// after
const READY_TIMEOUT: Duration = Duration::from_secs(180);

Defensive patterns

Strategy: retry

Try / catch

for _ in 0..3 {
    match TursoServer::spawn(&ctx).await {
        Ok(server) => return Ok(server),
        Err(e) if e.to_string().contains("did not become ready") => continue,
        Err(e) => return Err(e),
    }
}

Prevention

Keep test parallelism low enough that server startup fits the 60s budget
Run the server binary manually once to know its normal startup time
Watch for container sandbox rules that block listening sockets

When it happens

Trigger: The server binary hangs during startup (waiting on a lock, slow key generation, blocked on network); the machine is so loaded that bind+listen exceeds 60s; container seccomp or firewall rules silently drop the listen socket.

Common situations: CI runners executing many test shards in parallel; first-run costs like entropy or asset generation inside minimal containers; nested virtualization slowing everything down.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of tursodatabase/turso@492c4a71cd (2026-08-20). Data as JSON: /api/errors/dd15eeb77d7e6a88. Report an issue: GitHub.