Complete PR review requires

Error message

Complete PR review requires {} passes at {max_chars} characters per pass, but max_passes is {max_passes}. No review was run or posted. Opt in with max_passes/--max-passes of at least {} only after approving the provider spend and run duration.

What it means

After grouping patches into passes, plan_pr_review checks that the required pass count fits within max_passes. This ensure! fires when the diff needs more passes than the caller authorized. The message explicitly asks the user to opt in to the higher pass count only after approving the provider spend and run duration, because passes multiply cost linearly.

Solutions

Raise max_passes/--max-passes to at least the required count printed in the message, after approving the cost
Increase max_chars so fewer passes are needed
Review the PR in smaller chunks (split the PR) instead of one full review

Example fix

// before
plan_pr_review(diff, view, 20_000, 2)? // needs 5 passes
// after
plan_pr_review(diff, view, 20_000, 5)? // budget approved for 5 passes

Defensive patterns

Strategy: validation

Validate before calling

if estimated_passes(diff, max_chars) > max_passes { confirm_spend_with_user(estimated_passes)?; }

Try / catch

match plan_pr_review(...) { Err(e) if e.to_string().contains("requires") && e.to_string().contains("passes") => escalate_pass_budget_with_approval(e), other => other }

Prevention

Estimate pass count before running and require explicit cost approval
Keep max_chars and max_passes configured together (budget = chars x passes)
Split very large PRs instead of multiplying passes

When it happens

Trigger: Calling plan_pr_review where grouped.len() (patches grouped by max_chars) exceeds max_passes — a large PR reviewed with a small per-pass budget and a low pass cap.

Common situations: Default max_passes=1 or 2 with a big multi-file PR; user lowered max_chars for cost control without raising max_passes; first run of review on a monorepo-scale PR.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/6754a19438814c1d. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tools/review.rs:385

        );
    }

    let mut grouped: Vec<Vec<PrReviewPiece<'_>>> = Vec::new();
    let mut current: Vec<PrReviewPiece<'_>> = Vec::new();
    let mut current_chars = 0;
    for piece in pieces {
        let piece_chars = super::review_pr::model_diff(&piece.diff).chars().count();
        if !current.is_empty() && current_chars + piece_chars > max_chars {
            grouped.push(std::mem::take(&mut current));
            current_chars = 0;
        }
        current.push(piece);
        current_chars += piece_chars;
    }
    if !current.is_empty() {
        grouped.push(current);
    }
    anyhow::ensure!(
        grouped.len() <= max_passes,
        "Complete PR review requires {} passes at {max_chars} characters per pass, but max_passes is {max_passes}. No review was run or posted. Opt in with max_passes/--max-passes of at least {} only after approving the provider spend and run duration.",
        grouped.len(),
        grouped.len()
    );

    // The completeness guard, byte-for-byte as before: continuation parts
    // replay the file header, so exactly those repeated headers are stripped
    // and the rebuilt plan must equal the original diff.
    anyhow::ensure!(
        grouped
            .iter()
            .flatten()
            .map(|piece| &piece.diff[piece.header_bytes..])
            .collect::<String>()
            == diff,
        "PR review plan did not preserve the complete diff byte-for-byte"
    );

View on GitHub (pinned to 433685b202)