astrid-runtime/astrid · error

Invalid UUID format: {e}

Error message

Invalid UUID format: {e}

What it means

This error is raised in run_or_connect when the user-supplied --session value cannot be parsed as a UUID. The CLI parses the string with uuid::Uuid::parse_str before wrapping it in a SessionId; any string that is not a canonical (or hyphenated) 128-bit UUID fails the parse and the underlying uuid crate error is surfaced via anyhow.

Source

Thrown at crates/astrid-cli/src/bootstrap.rs:176

    workspace.or_else(|| std::env::current_dir().ok())
}

/// Resolve the session, check for an existing socket, and boot the
/// kernel locally if necessary. Drives the interactive-session path.
///
/// # Errors
/// Returns an error if the kernel fails to boot or the socket fails to connect.
pub(crate) async fn run_or_connect(
    session: Option<String>,
    workspace: Option<std::path::PathBuf>,
    format: OutputFormat,
) -> Result<()> {
    use astrid_core::SessionId;
    use uuid::Uuid;

    let session_id = if let Some(sid) = session {
        SessionId::from_uuid(
            Uuid::parse_str(&sid).map_err(|e| anyhow::anyhow!("Invalid UUID format: {e}"))?,
        )
    } else {
        SessionId::from_uuid(Uuid::new_v4())
    };
    let workspace_root = selected_workspace_root(workspace);

    let socket_path = socket_client::proxy_socket_path();
    let ready_path = socket_client::readiness_path();

    let outcome = astrid_core::local_transport::connect_outcome(&socket_path)
        .await
        .context("Failed to check socket")?;
    let action = commands::daemon::decide_ensure_action(
        &outcome,
        commands::daemon::recorded_daemon_pid_is_alive(),
    );
    let needs_boot = match action {
        commands::daemon::EnsureAction::UseExisting => {

View on GitHub (pinned to affd8760f4)

Solutions

1. Run the CLI without --session so a fresh UUID is generated
2. Validate the string with uuid::Uuid::parse_str before passing it
3. Check for shell-mangled characters (truncation, quotes, whitespace) in the value

Example fix

// before
astrid-cli --session main
// after
astrid-cli --session 550e8400-e29b-41d4-a716-446655440000

fn is_valid_uuid(s: &str) -> bool { uuid::Uuid::parse_str(s).is_ok() }
if !is_valid_uuid(&args.session) { eprintln!("--session must be a UUID"); std::process::exit(2); }

fn as_uuid(s: &str) -> Option<uuid::Uuid> { uuid::Uuid::parse_str(s).ok() }

match Uuid::parse_str(&sid) { Ok(u) => SessionId::from_uuid(u), Err(e) => { eprintln!("--session is not a UUID: {e}"); std::process::exit(2); } }

When it happens

Trigger: Passing --session with a non-UUID value such as a session name ('main'), a truncated ID, a UUID with invalid hex characters, or extra whitespace.

Common situations: Users passing a human-readable session label instead of an ID, copy-pasting a UUID that got truncated or mangled by the shell, or reusing a session ID from a different tool that uses non-UUID identifiers.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid session ID (must be a UUID): {id}
• --retain-entries must be at least 1
• --retain-bytes must be greater than 0
• --var has an empty key (got {item:?})
• --var '{key}' was supplied more than once

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/9203f1e85351574d. Report an issue: GitHub.