What causes "invalid --format value %q: must be 'text', 'json', or 'sarif'" in alibaba/open-code-review?

Use one of --format text, --format json, or --format sarif

invalid --format value %q: must be 'text', 'json', or 'sarif

Error message

invalid --format value %q: must be 'text', 'json', or 'sarif'

What it means

validateOutputFormat lowercases and trims --format, then accepts only text, json, or sarif. Anything else returns this error, echoing the original value. The normalized value replaces opts.outputFormat on success.

Source

Thrown at cmd/opencodereview/shared_flags.go:120

	return nil
}

func validateAudience(audience string) error {
	switch audience {
	case "human", "agent":
		return nil
	default:
		return fmt.Errorf("invalid --audience value %q: must be 'human' or 'agent'", audience)
	}
}

func validateOutputFormat(format string) (string, error) {
	normalized := strings.ToLower(strings.TrimSpace(format))
	switch normalized {
	case "text", "json", "sarif":
		return normalized, nil
	default:
		return "", fmt.Errorf("invalid --format value %q: must be 'text', 'json', or 'sarif'", format)
	}
}

func validateReviewOptions(opts *reviewOptions) error {
	if err := validateDiffMode(opts.from, opts.to, opts.commit); err != nil {
		return err
	}
	if opts.preview && opts.resume != "" {
		return fmt.Errorf("--preview and --resume cannot be used together")
	}
	if err := validateAudience(opts.audience); err != nil {
		return err
	}
	normalizedFormat, err := validateOutputFormat(opts.outputFormat)
	if err != nil {
		return err
	}
	opts.outputFormat = normalizedFormat

View on GitHub (pinned to 5cf97d0d15)

Solutions

Use one of --format text, --format json, or --format sarif
If you need markdown, produce it from --format json yourself downstream
Check --help for the supported formats of your installed ocr version
Fix the format variable in your pipeline configuration

Example fix

// before
ocr review --from main --to HEAD --format markdown
// after
ocr review --from main --to HEAD --format json

Defensive patterns

Strategy: validation

Validate before calling

case "$(echo "$FORMAT" | tr '[:upper:]' '[:lower:]')" in text|json|sarif) ;; *) echo "invalid format: $FORMAT"; exit 2;; esac

Type guard

function isOutputFormat(v) { return ['text','json','sarif'].includes(String(v).trim().toLowerCase()); }

Try / catch

ocr review --format "$FORMAT" 2>err.log || { grep -q 'invalid --format' err.log && ocr review --format text; }

Prevention

Stick to text, json, or sarif (case-insensitive)
Derive downstream artifacts (markdown, etc.) from JSON output instead of requesting it
Pin the format constant in pipeline configuration
Check --help for the version you run

When it happens

Trigger: Passing --format markdown, --format yaml, --format JSON+X, or an empty/whitespace string that fails the switch, from review (validateReviewOptions) or scan (validateScanOptions).

Common situations: Users assuming markdown output exists; YAML expectations from other tools; scripts passing a format variable from an unsupported pipeline; machine-readable consumers requesting formats the tool never supported.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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