sxyazi/yazi · error

--target is not valid for the install task

Error message

--target is not valid for the install task

What it means

The `yazi-build` CLI (shipped with the `ya` binary) validates that CLI flags are only passed to tasks that accept them. The `install` task copies already-built binaries into the Cargo bin directory, so a cross-compilation `--target` triple is meaningless there; passing one triggers this `ensure!` failure in `Args::parse`. It is an argument-contract error, not a runtime failure.

Source

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

				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}"))
	}

	fn target(args: &mut impl Iterator<Item = OsString>) -> Result<String> {
		Self::value(args, "--target")?
			.into_string()
			.map_err(|_| anyhow!("--target must be valid UTF-8"))
	}
}

View on GitHub (pinned to 5f901b886b)

Solutions

1. Remove the `--target <triple>` argument from the `ya install` command
2. If you need a specific pre-built binary installed, use `--bin-dir` to point at the directory containing the binaries instead of `--target`
3. If you meant to cross-compile, run `ya dist --target <triple>` (or `ya build --target <triple>`) first, then `ya install` without `--target`

Example fix

// before
ya install --target x86_64-unknown-linux-musl

// after
ya install --bin-dir ./target/x86_64-unknown-linux-musl/release
// or cross-compile first:
ya dist --target x86_64-unknown-linux-musl

const args = process.argv.slice(2);
if (args[0] === 'install' && args.includes('--target')) {
  throw new Error("--target is not valid for 'ya install'; use --bin-dir or 'ya dist --target' instead");
}

When it happens

Trigger: Running `ya install --target <triple>` (or `ya install --target x86_64-unknown-linux-gnu ...`). `--target` is only accepted by the `build` and `dist` tasks; `install` only accepts `--bin-dir`.

Common situations: Users copy-pasting a cross-compile command and swapping `dist` for `install`, or scripting a single arg string reused across build and install steps, accidentally keeping `--target` on the install invocation.

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

• --bin-dir is only valid for the install task
• the dist task requires --target
• invalid 'args' in SearchOpt
• chafa failed with status: {}
• unknown option: {}

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