Morganamilo/paru · error

unknown option

Error message

unknown option -{}

What it means

This error is raised from handle_arg (src/command_line.rs), reached via parse_arg, when the user supplied a short-form option that is not in the program's known option table. It fires in the fall-through arm of the Arg match: after parsing the single-character flag name out of a '-x' style token, handle_arg dispatches to the arm for each known short option, and an unrecognized character falls through to this bail. It is a usage/typo error (wrong or removed flag, or a value accidentally glued to a '-' such as '-foo' being read as '-f' plus 'oo'), so it terminates the parse before any configuration is applied.

Solutions

1. Verify the short flag against `--help` output
2. Replace the invalid short flag with the supported equivalent (often the long form)
3. Update scripts referencing flags removed in newer versions

Example fix

// before
paru -Z stats
// after
paru --stats

function is_known_short_flag(flag: string, known: Set<string>): boolean {
  return [...flag.replace(/^-/, '')].every(c => known.has(c));
}

match cli::parse(&args) {
    Err(e) if e.to_string().starts_with("unknown option -") => {
        eprintln!("{} — check --help for valid short flags", e);
        std::process::exit(2);
    }
    Err(e) => return Err(e),
    Ok(cmd) => cmd.run(),
}

When it happens

Trigger: Passing an unrecognized short flag such as `-z` or `-X` on the command line; combining grouped short flags where one letter is invalid (e.g. `-abc` when `-c` is unknown).

Common situations: Typos in short flags; muscle-memory flags from pacman/yay that this tool does not implement; outdated scripts.

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

• unknown option
• option expects a value
• option does not allow a value
• option must be a number
• no targets specified (use -h for help)

AI-assisted analysis of Morganamilo/paru@9ac3578807 (2026-09-12). Data as JSON: /api/errors/e4dfed132b35706b. Report an issue: GitHub.

Appendix: source

Thrown at src/command_line.rs:376

                    Ok(k) => Sign::Key(k.to_string()),
                    Err(_) => Sign::Yes,
                }
            }
            Arg::Long("nokeeprepocache") => self.keep_repo_cache = false,
            Arg::Long("keeprepocache") => self.keep_repo_cache = true,
            Arg::Long("signdb") => {
                self.sign_db = match value {
                    Ok(k) => Sign::Key(k.to_string()),
                    Err(_) => Sign::Yes,
                }
            }
            Arg::Long("nosign") => self.sign = Sign::No,
            Arg::Long("nosigndb") => self.sign_db = Sign::No,
            Arg::Long(a) if !arg.is_pacman_arg() && !arg.is_pacman_global() => {
                bail!(tr!("unknown option --{}", a))
            }
            Arg::Short(a) if !arg.is_pacman_arg() && !arg.is_pacman_global() => {
                bail!(tr!("unknown option -{}", a))
            }
            _ => (),
        }

        match takes_value(arg) {
            TakesValue::No if forced => bail!(tr!("option {} does not allow a value", arg)),
            _ => (),
        }

        Ok(())
    }
}

fn split_whitespace(s: &str) -> Vec<String> {
    s.split_whitespace().map(|s| s.to_string()).collect()
}

fn takes_value(arg: Arg) -> TakesValue {

View on GitHub (pinned to 9ac3578807)