nikivdev/code · error

no session-doc queue entry matches `{session_hint}`

Error message

no session-doc queue entry matches `{session_hint}`

What it means

When resolving a user-supplied session hint to a queue entry, the library filters entries by exact session_key or by prefix match. If zero entries match, it bails with this message instead of guessing. It means the hint is wrong or the entry no longer exists in the review queue file.

Source

Thrown at src/codex_session_docs.rs:1439

    project_root: &Path,
    session_hint: &str,
) -> Result<usize> {
    let project_root = project_root.display().to_string();
    let matches = entries
        .iter()
        .enumerate()
        .filter(|(_, entry)| {
            entry.target_root == project_root
                && (entry.session_id == session_hint
                    || entry.session_key == session_hint
                    || entry.session_id.starts_with(session_hint)
                    || entry.session_key.starts_with(session_hint))
        })
        .map(|(index, _)| index)
        .collect::<Vec<_>>();
    match matches.as_slice() {
        [index] => Ok(*index),
        [] => bail!("no session-doc queue entry matches `{session_hint}`"),
        _ => bail!("multiple session-doc queue entries match `{session_hint}`"),
    }
}

fn git_changed_paths(project_root: &Path) -> Result<Vec<String>> {
    let output = Command::new("git")
        .args(["status", "--porcelain", "--untracked-files=all"])
        .current_dir(project_root)
        .output()
        .context("failed to run git status")?;
    if !output.status.success() {
        bail!("git status failed with {}", output.status);
    }
    let stdout = String::from_utf8_lossy(&output.stdout);
    let mut paths = Vec::new();
    for line in stdout.lines() {
        if line.len() < 4 {
            continue;

View on GitHub (pinned to a747e741ae)

Solutions

1. List the current queue entries and copy the exact session_key
2. Shorten the hint to a valid prefix of the intended session_key
3. Re-run the flow that populates the queue if the entry is missing entirely

Example fix

// before
let idx = resolve_entry("sess_123")?; // bail if no match
// after
let idx = match try_resolve_entry("sess_123") {
    Ok(i) => i,
    Err(_) => { list_queue_entries()?; return Err(anyhow!("hint sess_123 not found; see list above")); }
};

let entries = load_queue(&queue_path)?;
let hit = entries.iter().find(|e| e.session_key == hint || e.session_key.starts_with(hint));
anyhow::ensure!(hit.is_some(), "hint `{hint}` matches no queue entry; available: {:?}",
    entries.iter().map(|e| &e.session_key).collect::<Vec<_>>());

fn resolves_unique(entries: &[DocReviewQueueEntry], hint: &str) -> Option<&DocReviewQueueEntry> {
    let m: Vec<_> = entries.iter().filter(|e| e.session_key == hint || e.session_key.starts_with(hint)).collect();
    (m.len() == 1).then(|| m[0])
}

match resolve_entry(hint) {
    Ok(i) => i,
    Err(e) if e.to_string().contains("no session-doc queue entry") => list_queue_and_prompt()?,
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling the resolve-queue-entry API (e.g. during doc review/promotion) with a `session_hint` string that matches neither an exact `session_key` nor a prefix of any entry in the queue.

Common situations: Typo in the session id; entry was already promoted/removed from the queue; pointing at a session from a different project root whose queue file differs.

Related errors

• multiple session-doc queue entries match `{session_hint}`
• No queued commit matches {}
• Multiple queued commits match {}. Use a longer hash.
• fzf not found on PATH – install it to use fuzzy selection.
• failed to resume codex session {}

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/e9d01602008b8dec. Report an issue: GitHub.