Due to Cargo's limitations, Yazi on crates.io must be built

Error message

Due to Cargo's limitations, Yazi on crates.io must be built with `cargo install --force yazi-build`

What it means

Raised by Action::get (yazi-shared/src/event/action.rs:124) when a command/action argument lookup by DataKey finds no entry in the args map. get() is the borrowed read accessor used by every command form (get("id"), first(), second(), seq()); it requires both presence and successful conversion, and absence produces this bail. It signals that the sender did not attach the expected named or positional argument.

Source

Thrown at yazi-fm/build.rs:22

	let dir = env::var("OUT_DIR").unwrap();

	// cargo build
	//   C:\Users\Ika\Desktop\yazi\target\release\build\yazi-fm-cfc94820f71daa30\out
	// cargo install
	//   C:\Users\Ika\AppData\Local\Temp\cargo-installTFU8cj\release\build\
	// yazi-fm-45dffef2500eecd0\out

	if dir.contains(r"\release\build\yazi-fm-") {
		panic!(
			"Unwinding must be enabled for Windows. Please use `cargo build --profile release-windows --locked` instead to build Yazi."
		);
	}

	let manifest = env::var_os("CARGO_MANIFEST_DIR").unwrap().to_string_lossy().replace(r"\", "/");
	if manifest.contains("/git/checkouts/yazi-")
		|| manifest.contains("/registry/src/index.crates.io-")
	{
		panic!(
			"Due to Cargo's limitations, Yazi on crates.io must be built with `cargo install --force yazi-build`"
		);
	}

	Ok(())
}

View on GitHub (pinned to 441b332de8)

Solutions

Compare the argument name at the emit site with the one the form reads — they must match exactly, including case
Attach the missing argument (use Action::with/with_opt on the Rust side or the correct key in Lua)
For positional args, verify earlier positions are present so indices don't shift
If the argument is genuinely optional, read it with the defaulted accessors (str/bool) or Option-based handling instead of get()

Example fix

-- before
ya.emit("update_spotted", { lok = lock })  -- receiver reads "lock"
-- after
ya.emit("update_spotted", { lock = lock })

Defensive patterns

Strategy: validation

Validate before calling

-- Lua: always attach the arguments the receiver reads
ya.emit("update", { id = id, name = name }) -- never omit required keys

Try / catch

// Rust: tolerate missing optional args
let id: Option<u64> = a.get("id").ok();

Prevention

Keep emitter argument names identical to the form's get() keys, including case
Prefer named arguments over positional ones to avoid index shifts
For optional values use defaulted accessors (str/bool) or Option on the Rust side
Write a smoke test per custom command that emits with all required args

When it happens

Trigger: A command form calling a.get::<T>("name") or a.first()/a.second() when the action was built without that key; typo or case mismatch in an argument name between emitter and receiver (DataKey::String is exact-match); positional args shifted because an earlier one was omitted; parsing a keymap string whose option syntax did not produce the expected key.

Common situations: Custom keymap entries missing a required option (e.g. a command needing --ratio without it); plugin emitting a command with renamed arguments after a yazi upgrade; hand-written Action strings in config where quoting swallowed an argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of sxyazi/yazi@441b332de8 (2026-08-19). Data as JSON: /api/errors/15d55a66f271c3fd. Report an issue: GitHub.