alibaba/open-code-review · error

"%q %s" (+ positional signature, valid values, usage line, e

Error message

"%q %s" (+ positional signature, valid values, usage line, example) + "Run '<command-path> --help' for more information."

What it means

argCountError builds a rich usage error: the invalid invocation with positional signature, valid values, usage line and an example, terminated by a pointer to '<command-path> --help'. It is thrown when a cobra command receives the wrong number of positional arguments.

Source

Thrown at cmd/opencodereview/arg_errors.go:73

	if len(cmd.ValidArgs) > 0 {
		b.WriteString("\n\nValid values: ")
		b.WriteString(strings.Join(validArgNames(cmd.ValidArgs), ", "))
	}

	b.WriteString("\n\nUsage:\n  ")
	b.WriteString(cmd.UseLine())

	if example := strings.TrimRight(cmd.Example, "\n"); example != "" {
		b.WriteString("\n\nExample:\n")
		b.WriteString(example)
	}

	b.WriteString("\n\nRun '")
	b.WriteString(path)
	b.WriteString(" --help' for more information.")

	return errors.New(b.String())
}

// positionalSignature extracts the positional-argument part of cmd.Use, e.g.
// "<key> <value>" from "set <key> <value>" and "<path...>" from
// "rule [flags] <path...>". Bracketed fields are not placeholders the user
// types, so "[flags]" and inline enumerations such as "[bash|zsh]" are dropped;
// enumerated values are reported from ValidArgs instead.
func positionalSignature(cmd *cobra.Command) string {
	fields := strings.Fields(cmd.Use)
	if len(fields) < 2 {
		return ""
	}

	parts := make([]string, 0, len(fields)-1)
	for _, f := range fields[1:] {
		if strings.HasPrefix(f, "<") {
			parts = append(parts, f)
		}

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Run the exact suggested command, e.g. 'ocr <command-path> --help', to see the canonical usage line and example.
2. Re-run with the correct number of positional arguments as shown in the usage line.
3. Quote arguments containing spaces so they count as a single positional.
4. Check the release notes/changelog for renamed or restructured subcommands if the syntax used to work.

Example fix

// before
ocr rule
// after
ocr rule .config/ocr/rules.yml   # see: ocr rule --help

// shell pre-check before invoking
case $# in
  0) echo "error: missing arguments; run 'ocr <command> --help'" >&2; exit 2;;
esac
ocr rule "$@"

try:
    subprocess.run(['ocr', 'rule', path], check=True)
except subprocess.CalledProcessError as e:
    print(e.stderr)  # contains the usage line and --help pointer
    sys.exit(2)

When it happens

Trigger: Invoking any ocr subcommand with a positional count that violates its Args validation — e.g. 'ocr rule' with no path, or 'ocr set' with fewer than two arguments.

Common situations: Typos that make a flag value look like a positional argument; forgetting an argument entirely; quoting mistakes splitting one argument into many; scripting with stale command syntax after an upgrade.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• read background file %q: %w
• background file %q is a directory, not a file
• background file %q is %d bytes, exceeding the maximum of %d
• MCP server %q not found
• custom provider %q not found

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