--max-tokens must be a non-negative integer (0 means use con

Error message

--max-tokens must be a non-negative integer (0 means use configured or template default)

What it means

--max-tokens caps the agent's token usage; negatives are invalid, while 0 means 'use the configured or template default'. validateReviewOptions rejects negative values with this message, immediately after the maxGitProcs check.

Source

Thrown at cmd/opencodereview/shared_flags.go:151

	}
	normalizedFormat, err := validateOutputFormat(opts.outputFormat)
	if err != nil {
		return err
	}
	opts.outputFormat = normalizedFormat
	const minMaxTools = 50
	if opts.maxTools < 0 {
		return fmt.Errorf("--max-tools must be a non-negative integer (0 means use template default)")
	}
	if opts.maxTools > 0 && opts.maxTools < minMaxTools {
		fmt.Fprintf(os.Stderr, "[ocr] --max-tools %d is below minimum %d, using %d\n", opts.maxTools, minMaxTools, minMaxTools)
		opts.maxTools = minMaxTools
	}
	if opts.maxGitProcs < 0 {
		return fmt.Errorf("--max-git-procs must be a non-negative integer (0 means use default 16)")
	}
	if opts.maxTokens < 0 {
		return fmt.Errorf("--max-tokens must be a non-negative integer (0 means use configured or template default)")
	}
	if opts.maxTokensBudget < 0 {
		return fmt.Errorf("--max-tokens-budget must be a non-negative integer (0 means unlimited)")
	}
	if opts.effort != "" {
		if _, err := template.ParseEffort(opts.effort); err != nil {
			return fmt.Errorf("--effort: %w", err)
		}
	}
	return nil
}

func validateScanOptions(opts *scanOptions) error {
	if err := validateAudience(opts.audience); err != nil {
		return err
	}
	normalizedFormat, err := validateOutputFormat(opts.outputFormat)
	if err != nil {

View on GitHub (pinned to 5cf97d0d15)

Solutions

Pass a non-negative value; --max-tokens 0 selects the configured/template default
Fix the budget calculation that produced the negative number
Remove the flag to inherit configuration defaults
Validate config-driven values before passing them through

Example fix

// before
LIMIT=$(( TOTAL - SPENT )); ocr review --max-tokens "$LIMIT"   # negative
// after
LIMIT=$(( TOTAL > SPENT ? TOTAL - SPENT : 0 )); ocr review --max-tokens "$LIMIT"

Defensive patterns

Strategy: validation

Validate before calling

case "$MAX_TOKENS" in ''|*[!0-9]*) echo "max-tokens must be a non-negative integer, got: $MAX_TOKENS"; exit 2;; esac

Type guard

function isNonNegativeInt(v) { return Number.isInteger(v) && v >= 0; }

Try / catch

ocr review --max-tokens "$MAX_TOKENS" 2>err.log || { grep -q 'max-tokens must be a non-negative' err.log && ocr review --max-tokens 0; }

Prevention

Remember 0 means 'configured/template default'; unlimited budget is --max-tokens-budget 0
Clamp budget math so it never emits negatives
Validate numbers coming from config files before forwarding
Omit the flag to rely on defaults

When it happens

Trigger: Passing --max-tokens -1000 (or any negative) to review — the opts.maxTokens < 0 branch in validateReviewOptions, reached from the review command's anonymous caller.

Common situations: Budget math in scripts yielding negative numbers; confusing 'unlimited' (which is --max-tokens-budget 0) with a negative sentinel; stale config files containing -1 as a placeholder.

Related errors

AI-assisted analysis of alibaba/open-code-review@5cf97d0d15 (2026-09-02). Data as JSON: /api/errors/721bfc23b84dbda4. Report an issue: GitHub.