sxyazi/yazi · error

unknown option: {}

Error message

unknown option: {}

What it means

The `yazi-build` argument parser only accepts the flags `--target`, `--bin-dir`, and `--help` while iterating over CLI arguments. Any argument that is not one of these (and is not the task name `build` or `install`) causes the parser to bail with `unknown option: <arg>`. It is a usage/CLI contract error thrown from `Args::parse` in yazi-build/src/args.rs.

Source

Thrown at yazi-build/src/args.rs:24

	Build(String),
	Dest(String),
	Install(PathBuf),
	Help,
}

impl Args {
	pub(super) fn parse() -> Result<Self> {
		let mut args = env::args_os().skip(1);
		let task = args.next().unwrap_or_else(|| "--help".into());

		let mut target = String::new();
		let mut bin_dir = PathBuf::new();
		while let Some(arg) = args.next() {
			match arg.to_str() {
				Some("--target") => target = Self::target(&mut args)?,
				Some("--bin-dir") => bin_dir = Self::value(&mut args, "--bin-dir")?.into(),
				Some("--help") => return Ok(Self::Help),
				_ => bail!("unknown option: {}", arg.display()),
			}
		}

		match task.to_str() {
			Some("build") => {
				ensure!(bin_dir.as_os_str().is_empty(), "--bin-dir is only valid for the install task");
				Ok(Self::Build(target))
			}
			Some("dist") => {
				ensure!(!target.is_empty(), "the dist task requires --target");
				ensure!(bin_dir.as_os_str().is_empty(), "--bin-dir is only valid for the install task");
				Ok(Self::Dest(target))
			}
			Some("install") => {
				ensure!(target.is_empty(), "--target is not valid for the install task");
				Ok(Self::Install(bin_dir))
			}
			Some("--help") => Ok(Self::Help),

View on GitHub (pinned to 5f901b886b)

Solutions

1. Check the argument spelling against the supported set: `--target <triple>`, `--bin-dir <path>`, `--help`, and the task names `build`/`install`.
2. Run with `--help` (or read yazi-build/src/args.rs) to list the accepted options for your version.
3. Fix the invoker (script, CI config, cargo alias in .cargo/config.toml) to pass only supported flags.

Example fix

// before
cargo yazi build --prefix ~/.local
// after
cargo yazi install --bin-dir ~/.local/bin

const VALID_OPTS = ["--target", "--bin-dir", "--help"];
if (!VALID_OPTS.includes(arg) && !["build", "install"].includes(task)) {
  throw new Error(`unknown option: ${arg} (valid: ${VALID_OPTS.join(", ")})`);
}

When it happens

Trigger: Running `cargo yazi --some-flag ...` or `cargo yazi build --foo` with a flag not in {`--target`, `--bin-dir`, `--help`}; misspelling a flag (e.g. `--bin_dir` or `--targe`); passing positional junk arguments.

Common situations: Typo in a flag in a script or Makefile; copying flags from an older version of the build helper that supported different options; putting `--bin-dir` before the `build` task and confusing the parser ordering.

Related errors

• unknown task: {}
• chafa failed with status: {}
• --target must be valid UTF-8
• --bin-dir is only valid for the install task
• the dist task requires --target

AI-assisted analysis of sxyazi/yazi@5f901b886b (2026-09-02). Data as JSON: /api/errors/425bf2f633d83abd. Report an issue: GitHub.