xai-org/grok-build · error

session '{name}' not found

Error message

session '{name}' not found

What it means

lookup_session() reads `<registry_dir>/<name>.json` to resolve a named session. If the file does not exist, the name is unknown and this error is returned.

Source

Thrown at crates/codegen/ptyctl-cli/src/registry.rs:53

    let path = dir.join(format!("{name}.json"));
    let json = serde_json::to_string_pretty(info)?;

    // Atomic write: write to temp file, then rename.
    let tmp = dir.join(format!(".{name}.json.tmp"));
    fs::write(&tmp, &json).context("failed to write session file")?;
    fs::rename(&tmp, &path).context("failed to rename session file")?;

    Ok(())
}

/// Look up a named session.
pub fn lookup_session(name: &str) -> Result<SessionInfo> {
    let dir = registry_dir()?;
    let path = dir.join(format!("{name}.json"));

    if !path.exists() {
        bail!("session '{name}' not found");
    }

    let json = fs::read_to_string(&path).context("failed to read session file")?;
    let info: SessionInfo = serde_json::from_str(&json).context("failed to parse session file")?;

    Ok(info)
}

/// Remove a named session.
pub fn unregister_session(name: &str) -> Result<()> {
    let dir = registry_dir()?;
    let path = dir.join(format!("{name}.json"));
    if path.exists() {
        fs::remove_file(&path).context("failed to remove session file")?;
    }
    Ok(())
}

View on GitHub (pinned to bc7f02eddd)

Solutions

1. List existing sessions (`ptyctl list` or ls the registry dir) and use a valid name
2. Start the session first: `ptyctl run --name <n> ...`
3. Check for typos in the name
4. Confirm you run as the same user (registry dir is per-user/HOME-dependent)

Example fix

// before
ptyctl screen --name devsession
// after (after listing available names)
ptyctl screen --name dev-session

fn ensure_session_known(name: &str) -> anyhow::Result<()> {
    let dir = registry_dir()?;
    if !dir.join(format!("{name}.json")).exists() {
        anyhow::bail!("session '{name}' not registered; run 'ptyctl list' or start it first");
    }
    Ok(())
}

match registry::lookup_session(name) {
    Ok(info) => use_session(info),
    Err(e) if e.to_string().contains("not found") => {
        eprintln!("unknown session; pick a valid name from 'ptyctl list'");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Any operation targeting a session by name (--name, stop, screen, keys, to_url with name) when no `<name>.json` exists in the registry directory — the session was never created with that name or the registry was cleared.

Common situations: Typo in session name; running commands from a different user/HOME so the registry dir differs; registry cleaned between test runs; session never started.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Plugin "{name}" not found. Run `grok plugin list` to see ins
• Session does not exist: {}
• Session does not exist
• Marketplace source "{filter}" not found.
• worktree not found: {id_or_path}

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