session '{session_name}' is already running on port {} (use

Error message

session '{session_name}' is already running on port {} (use --force to replace it)

What it means

run() refuses to start a new session under a name whose registered server is still reachable, to avoid hijacking a live session. Use --force to deliberately replace it; stale (unreachable) entries are replaced automatically.

Source

Thrown at crates/codegen/ptyctl-cli/src/commands/run.rs:37

    command: Vec<String>,
    width: u16,
    height: u16,
    cwd: Option<PathBuf>,
    env_vars: Vec<String>,
    port: u16,
    name: Option<String>,
    force: bool,
    timeout: Option<u64>,
    linger: bool,
    quiet: bool,
) -> Result<()> {
    // Refuse to take over a name whose server is still reachable unless --force; stale entries are replaced.
    if let Some(ref session_name) = name
        && !force
        && let Ok(existing) = registry::lookup_session(session_name)
        && registry::server_alive(existing.port).await
    {
        bail!(
            "session '{session_name}' is already running on port {} (use --force to replace it)",
            existing.port
        );
    }

    // Parse env vars.
    let mut env = HashMap::new();
    for var in &env_vars {
        if let Some((k, v)) = var.split_once('=') {
            env.insert(k.to_string(), v.to_string());
        }
    }

    let cwd_str = cwd
        .as_ref()
        .map(|p| p.display().to_string())
        .unwrap_or_else(|| ".".into());

View on GitHub (pinned to bc7f02eddd)

Solutions

Add --force to replace the running session: `ptyctl run --name <n> --force ...`
Stop the existing session first (`ptyctl stop --name <n>`), then run
Pick a different session name for the new instance
Check who holds the port (`ss -ltnp`) and kill the old process if orphaned

Example fix

// before
ptyctl run --name dev -- bash
// after
ptyctl run --name dev --force -- bash

Defensive patterns

Strategy: validation

Validate before calling

if let Ok(existing) = registry::lookup_session(name)
    && registry::server_alive(existing.port).await
{
    eprintln!("session '{}' alive on port {} — stop it or use --force", name, existing.port);
    std::process::exit(1);
}

Prevention

Check `ptyctl list` / port liveness before starting a named session
Use unique session names per CI job to avoid collisions
Prefer stop-then-run over --force when unsure what holds the port

When it happens

Trigger: Calling `ptyctl run --name <n> ...` (without --force) while a live server already listens on the port registered for that name in the registry.

Common situations: Re-running a command that's already running in another terminal; a leftover background server still serving; parallel CI jobs colliding on the same session name.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/44d9b273b8b83649. Report an issue: GitHub.