sxyazi/yazi · error

unknown task: {}

Error message

unknown task: {}

What it means

After option parsing, `Args::parse` matches the first positional argument (the task) against `build`, `install`, and `--help`. Any other task name bails with `unknown task: <task>`. This enforces that the cargo subcommand is invoked with exactly one of the supported tasks.

Source

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

			}
		}

		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. Use `build` or `install` as the task: `cargo yazi build` or `cargo yazi install --bin-dir <dir>`.
2. Run `cargo yazi --help` to see valid tasks for your installed version.
3. Update any automation that references an old task name.

Example fix

// before
cargo yazi release
// after
cargo yazi build

const TASKS = ["build", "install"];
if (!TASKS.includes(process.argv[2])) {
  throw new Error(`unknown task: ${process.argv[2]} (valid: ${TASKS.join(", ")})`);
}

When it happens

Trigger: Running `cargo yazi deploy`, `cargo yazi Build`, `cargo yazi` with a typo like `instal`, or accidentally passing a flag-like token as the first positional.

Common situations: Typo in package.json / CI scripts; muscle memory from other cargo helpers (`cargo yank`, `cargo install`); outdated documentation referencing a removed task.

Related errors

• unknown option: {}
• 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/c6eec4cba662ffa2. Report an issue: GitHub.