nikivdev/code · error

session is not eligible for promotion

Error message

session is not eligible for promotion

What it means

This library refuses to promote a codex session into documentation when the pre-computed preview reports the session as ineligible. The error surfaces `preview.blocked_reason` when one is set, otherwise a generic message. It is a deliberate guard so only sessions that passed all eligibility checks (e.g. clean state, required docs present) get promoted.

Source

Thrown at src/codex_session_docs.rs:393

    let preview = SessionPromotionPreview {
        session_id: packet.session_id.clone(),
        session_key: session_key.clone(),
        target_path: target_path.clone(),
        eligible: entries[entry_index].promotion_eligible.unwrap_or(false),
        review_state: entries[entry_index].doc_review_state.clone(),
        promotion_reason: entries[entry_index]
            .promotion_reason
            .clone()
            .unwrap_or_else(|| "no promotion reason recorded".to_string()),
        blocked_reason: entries[entry_index].blocked_reason.clone(),
        markdown,
    };
    if !apply {
        write_review_queue_entries(&queue_path, &entries)?;
        return Ok(preview);
    }
    if !preview.eligible {
        bail!(
            "{}",
            preview
                .blocked_reason
                .clone()
                .unwrap_or_else(|| "session is not eligible for promotion".to_string())
        );
    }

    let promoted_path = resolve_project_relative_path(project_root, &target_path);
    if let Some(parent) = promoted_path.parent() {
        fs::create_dir_all(parent)
            .with_context(|| format!("failed to create {}", parent.display()))?;
    }
    fs::write(&promoted_path, &preview.markdown)
        .with_context(|| format!("failed to write {}", promoted_path.display()))?;

    let promoted_path_string = promoted_path.display().to_string();
    if !entries[entry_index]

View on GitHub (pinned to a747e741ae)

Solutions

1. Read the `blocked_reason` printed in the error (or rerun the preview step) to see the exact ineligibility cause
2. Fix the underlying cause (generate/repair the session docs, complete prerequisites) and rerun promotion
3. If the session was already promoted, skip it instead of re-running promotion

Example fix

// before
apply_promotion(preview);
// after
if preview.eligible {
    apply_promotion(preview);
} else {
    eprintln!("skipped: {}", preview.blocked_reason.as_deref().unwrap_or("ineligible"));
}

if !preview.eligible {
    eprintln!("skipping promotion: {}", preview.blocked_reason.as_deref().unwrap_or("ineligible"));
    return;
}
apply_promotion(preview);

fn is_promotable(preview: &Preview) -> bool {
    preview.eligible && preview.blocked_reason.is_none()
}

match promote(preview) {
    Ok(result) => result,
    Err(e) if e.to_string().contains("not eligible") => skip_session(&e.to_string()),
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling the doc promotion flow (after the `apply` flag is set and the preview was computed) while `preview.eligible == false`; the blocked reason stored in the preview is bubbled up verbatim.

Common situations: Running promotion on a session whose doc artifacts were never generated, on a session already promoted, or on a session that failed a prerequisite check earlier in the pipeline.

Related errors

• fzf not found on PATH – install it to use fuzzy selection.
• failed to resume codex session {}
• failed to resume {} session {}
• Session name '{}' already exists. Use a different name or re
• Session '{}' not found in saved sessions

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