{"record":{"id":"44d9b273b8b83649","repo":"xai-org/grok-build","slug":"session-session-name-is-already-running-on-por","errorCode":null,"errorMessage":"session '{session_name}' is already running on port {} (use --force to replace it)","messagePattern":"session '(.+?)' is already running on port (.+?) \\(use --force to replace it\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/ptyctl-cli/src/commands/run.rs","lineNumber":37,"sourceCode":"    command: Vec<String>,\n    width: u16,\n    height: u16,\n    cwd: Option<PathBuf>,\n    env_vars: Vec<String>,\n    port: u16,\n    name: Option<String>,\n    force: bool,\n    timeout: Option<u64>,\n    linger: bool,\n    quiet: bool,\n) -> Result<()> {\n    // Refuse to take over a name whose server is still reachable unless --force; stale entries are replaced.\n    if let Some(ref session_name) = name\n        && !force\n        && let Ok(existing) = registry::lookup_session(session_name)\n        && registry::server_alive(existing.port).await\n    {\n        bail!(\n            \"session '{session_name}' is already running on port {} (use --force to replace it)\",\n            existing.port\n        );\n    }\n\n    // Parse env vars.\n    let mut env = HashMap::new();\n    for var in &env_vars {\n        if let Some((k, v)) = var.split_once('=') {\n            env.insert(k.to_string(), v.to_string());\n        }\n    }\n\n    let cwd_str = cwd\n        .as_ref()\n        .map(|p| p.display().to_string())\n        .unwrap_or_else(|| \".\".into());\n","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/ptyctl-cli/src/commands/run.rs#L19-L55","documentation":"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.","triggerScenarios":"Calling `ptyctl run --name <n> ...` (without --force) while a live server already listens on the port registered for that name in the registry.","commonSituations":"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.","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"],"exampleFix":"// before\nptyctl run --name dev -- bash\n// after\nptyctl run --name dev --force -- bash","handlingStrategy":"validation","validationCode":"if let Ok(existing) = registry::lookup_session(name)\n    && registry::server_alive(existing.port).await\n{\n    eprintln!(\"session '{}' alive on port {} — stop it or use --force\", name, existing.port);\n    std::process::exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","port-conflict","session"],"backgroundTag":"port-already-in-use","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}