sxyazi/yazi · error

--bin-dir is only valid for the install task

Error message

--bin-dir is only valid for the install task

What it means

yazi-build's argument parser rejects the `--bin-dir` flag whenever the chosen task is not `install` — for the `build` task it's meaningless since no binaries are placed into a bin directory. `ensure!` turns the violation into this anyhow error.

Source

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

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),
			_ => bail!("unknown task: {}", task.display()),
		}
	}

	fn value(args: &mut impl Iterator<Item = OsString>, option: &str) -> Result<OsString> {
		args.next().with_context(|| format!("missing value for {option}"))

View on GitHub (pinned to 5f901b886b)

Solutions

1. Remove `--bin-dir` when invoking the build task
2. Use the `install` task if you want binaries placed in a bin dir
3. If you need a custom output location for build, check if `--target` or env vars like CARGO_TARGET_DIR apply

Example fix

// before
ya-build build --bin-dir ~/.local/bin
// after
ya-build install --bin-dir ~/.local/bin

if task == "build" && args.contains("--bin-dir") {
    eprintln!("--bin-dir requires the install task");
    std::process::exit(2);
}

match parse_result {
    Err(e) if e.to_string().contains("--bin-dir is only valid for the install task") => {
        eprintln!("usage: ya-build install --bin-dir <path>");
    }
    other => other,
}

When it happens

Trigger: Running `ya-build build --bin-dir <path>` — the parser matches task "build" and finds `bin_dir` non-empty.

Common situations: Copy-pasting an install command line and changing only the task word to `build`; scripted builds sharing a flag matrix across tasks.

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

• the dist task requires --target
• --target must be valid UTF-8
• --target is not valid for the install task
• invalid 'args' in SearchOpt
• chafa failed with status: {}

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