alibaba/open-code-review · error

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

Error message

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

What it means

validateDelegateOptions in cmd/opencodereview/shared_flags.go validates the --format flag for the delegate command. Only 'text' and 'json' are accepted; any other value produces this error with the offending value quoted via %q. Validation happens after the diff-mode check and before any delegation work starts.

Source

Thrown at cmd/opencodereview/shared_flags.go:196

	}
	if opts.maxTokens < 0 {
		return fmt.Errorf("--max-tokens must be a non-negative integer (0 means use configured or template default)")
	}
	if opts.preview && opts.resume != "" {
		return fmt.Errorf("--preview and --resume cannot be used together")
	}
	if opts.maxTokensBudget < 0 {
		return fmt.Errorf("--max-tokens-budget must be a non-negative integer (0 means unlimited)")
	}
	return nil
}

func validateDelegateOptions(opts *delegateOptions) error {
	if err := validateDiffMode(opts.from, opts.to, opts.commit); err != nil {
		return err
	}
	if opts.format != "text" && opts.format != "json" {
		return fmt.Errorf("invalid --format value %q: must be 'text' or 'json'", opts.format)
	}
	return nil
}

// registerReviewFlags registers all review command flags on cmd, binding to opts.
func registerReviewFlags(cmd *cobra.Command, opts *reviewOptions) {
	addToolsFlag(cmd, &opts.toolConfigPath)
	addRuleFlag(cmd, &opts.rulePath)
	addRepoFlag(cmd, &opts.repoDir)
	addDiffFlags(cmd, &opts.from, &opts.to, &opts.commit)
	cmd.Flags().StringVar(&opts.resume, "resume", "", "resume from a previous review session id")
	cmd.RegisterFlagCompletionFunc("resume", completeSessionIDs)
	addExcludeFlag(cmd, &opts.excludes)
	addOutputFlags(cmd, &opts.outputFormat, &opts.audience)
	addOutputPathFlag(cmd, &opts.outputPath)
	addConcurrencyFlags(cmd, &opts.concurrency, &opts.perFileTimeout, &opts.maxTools, &opts.maxGitProcs, &opts.maxTokens, &opts.maxTokensBudget)
	addBackgroundFlags(cmd, &opts.background, &opts.backgroundFile)
	addProviderFlag(cmd, &opts.provider)

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Use --format text or --format json exactly (lowercase)
2. Omit --format if the default already suits you
3. Fix the variable in your wrapper script to be one of the two accepted values

Example fix

// before
ocr delegate --format JSON
// after
ocr delegate --format json

case "$FORMAT" in text|json) ;; *) echo "invalid --format: $FORMAT" >&2; exit 2;; esac
ocr delegate --format "$FORMAT"

When it happens

Trigger: Running `ocr delegate --format yaml`, `--format markdown`, `--format JSON` (case-sensitive, so uppercase fails), or an empty --format value.

Common situations: Copying format names from other CLIs that accept yaml/markdown; shell variables defaulting to something other than text/json; assuming case-insensitive parsing.

Related errors

• --effort: %w
• invalid --color value %q: must be one of auto, always, never
• --max-tokens-budget must be a non-negative integer (0 means
• "%q %s" (+ positional signature, valid values, usage line, e
• read background file %q: %w

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