{"record":{"id":"dc9ebeb3df01d54a","repo":"xai-org/grok-build","slug":"error-session-id-must-be-a-valid-uuid-got-se","errorCode":null,"errorMessage":"Error: --session-id must be a valid UUID (got '{session_id}').","messagePattern":"Error: --session-id must be a valid UUID \\(got '(.+?)'\\)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-pager/src/app/session_startup.rs","lineNumber":796,"sourceCode":"    );\n    auth\n}\n/// Pre-TUI remote restore (session state and memory only).\n/// Codebase checkout is never applied on this path; `--restore-code` requires `--worktree`.\nconst REMOTE_RESTORE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(90);\n/// `--restore-code` without `--worktree` on a remote miss: refuse in-place checkout.\nconst REMOTE_RESTORE_NEEDS_WORKTREE: &str = \"--restore-code on a remote session requires --worktree \\\n     (refusing to check out snapshot code into the current directory)\";\n/// `--worktree` resume without `--restore-code`: conversation only.\npub(crate) const WORKTREE_NO_RESTORE_CODE_NOTICE: &str =\n    \"Snapshot code will not be restored into the worktree; pass --restore-code to restore it.\";\n/// Preflight: preferred id must be a UUID and not a persisted session under `cwd`.\n///\n/// Agent `session/new` rejects non-UUID `_meta.sessionId`; fail fast here so\n/// CLI users get a clear error before ACP.\npub fn ensure_session_id_available(session_id: &str, cwd: &str) -> anyhow::Result<()> {\n    if uuid::Uuid::try_parse(session_id).is_err() {\n        anyhow::bail!(\"Error: --session-id must be a valid UUID (got '{session_id}').\");\n    }\n    if xai_grok_shell::session::persistence::session_exists_for_cwd(session_id, cwd) {\n        anyhow::bail!(\"Error: Session ID {session_id} is already in use.\");\n    }\n    Ok(())\n}\n/// Materialize CLI intent into a concrete startup plan (I/O + remote restore).\npub async fn materialize_startup(\n    ctx: MaterializeCtx,\n    intent: SessionStartupIntent,\n) -> anyhow::Result<MaterializedStartup> {\n    let cwd = std::env::current_dir()\n        .map_err(|e| anyhow::anyhow!(\"Failed to get cwd: {e}\"))?\n        .to_string_lossy()\n        .to_string();\n    materialize_startup_for_cwd(ctx, intent, &cwd).await\n}\n/// Same as [`materialize_startup`] but with an explicit process cwd (tests, headless).","sourceCodeStart":778,"sourceCodeEnd":814,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-pager/src/app/session_startup.rs#L778-L814","documentation":"`ensure_session_id_available` is a preflight check run before the ACP `session/new` handshake. Because the agent rejects any non-UUID `_meta.sessionId`, the CLI fails fast with this clear message when the `--session-id` value cannot be parsed by `uuid::Uuid::try_parse`. This surfaces the problem at CLI startup instead of as an opaque protocol error mid-handshake.","triggerScenarios":"Calling `ensure_session_id_available(session_id, cwd)` (or the CLI `--session-id` flag it backs) with a string that is not a valid UUID, e.g. a name like 'my-session', a truncated UUID, or one with invalid characters.","commonSituations":"Typing a descriptive session name instead of a UUID; copying a UUID with extra characters or missing a segment; old configs from a version that accepted arbitrary session-id strings; shell interpolation producing an empty or partial value for `--session-id`.","solutions":["Pass a valid UUID for `--session-id`, e.g. generate one with `uuidgen` or `python -c 'import uuid; print(uuid.uuid4())'`.","If you just want a fresh session, drop `--session-id` entirely and let the CLI use `SessionStartupIntent::NewAuto`.","If resuming an existing session, use `--resume` with the stored session's ID rather than re-typing it.","Trim/copy the UUID carefully — validate locally with `Uuid::parse_str` or a regex before invoking."],"exampleFix":"// before\nxai-grok --session-id my-session\n// after\nNEW_ID=$(uuidgen)\nxai-grok --session-id \"$NEW_ID\"","handlingStrategy":"validation","validationCode":"use uuid::Uuid;\nfn validate_session_id(session_id: &str) -> Result<(), String> {\n    Uuid::try_parse(session_id)\n        .map(|_| ())\n        .map_err(|_| format!(\"--session-id must be a valid UUID (got '{session_id}').\"))\n}\n// call before launching: validate_session_id(&args.session_id)?;","typeGuard":"fn is_valid_uuid(s: &str) -> bool {\n    uuid::Uuid::try_parse(s).is_ok()\n}","tryCatchPattern":"match ensure_session_id_available(&session_id, cwd) {\n    Err(e) if e.to_string().contains(\"must be a valid UUID\") => {\n        eprintln!(\"Please pass a proper UUID, e.g. --session-id $(uuidgen)\");\n        std::process::exit(1);\n    }\n    other => other?,\n}","preventionTips":["Generate IDs with uuidgen / Uuid::new_v4() instead of typing them.","Validate UUID format in wrapper scripts before invoking the CLI.","Prefer omitting --session-id (NewAuto) unless an explicit ID is required.","Copy-paste UUIDs in full; check for truncation, whitespace, or surrounding quotes."],"tags":["cli","uuid","validation","session-id"],"backgroundTag":"invalid-uuid-format","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}