What causes "plugin name cannot be empty" in sxyazi/yazi?

Add the plugin name as the first argument of the plugin action, e.g. `plugin my-plugin --args`.

plugin name cannot be empty

Error message

plugin name cannot be empty

What it means

Converting an ActionCow into PluginOpt (yazi-core/src/app/plugin.rs:33) requires the action's first argument to be a non-empty plugin name. If the first argument is missing or empty, the conversion bails because a plugin invocation is meaningless without a name.

Source

Thrown at yazi-core/src/app/plugin.rs:33

#[derive(Clone, Debug, Default)]
pub struct PluginOpt {
	pub name:     SStr,
	pub args:     HashMap<DataKey, Data>,
	pub mode:     PluginMode,
	pub method:   PluginMethod,
	pub scope:    Scope,
	pub callback: Option<Box<dyn PluginCallback>>,
}

impl_data_any!(PluginOpt);

impl TryFrom<ActionCow> for PluginOpt {
	type Error = anyhow::Error;

	fn try_from(mut a: ActionCow) -> Result<Self, Self::Error> {
		let Some(name) = a.take_first::<SStr>().ok().filter(|s| !s.is_empty()) else {
			bail!("plugin name cannot be empty");
		};

		let args = if let Ok(s) = a.second() {
			let (words, last) = yazi_shared::shell::unix::split(s, true)?;
			Cmd::parse_args(words, last)?
		} else {
			a.take_second().unwrap_or_default()
		};

		Ok(Self {
			name: Self::normalize_name(name),
			args,
			mode: a.str("mode").parse().unwrap_or_default(),
			method: a.str("method").parse().unwrap_or_default(),
			scope: a.take_any("scope").unwrap_or_default(),
			callback: a.take_any("callback"),
		})
	}

View on GitHub (pinned to 5f901b886b)

Solutions

Add the plugin name as the first argument of the plugin action, e.g. `plugin my-plugin --args`.
Check keymap/config strings for missing or accidentally quoted-away plugin names.
In code, guard the plugin name variable for emptiness before dispatching the action.

Example fix

// before
run = "plugin"
// after
run = "plugin smart-enter"

Defensive patterns

Strategy: validation

Validate before calling

let name = plugin_arg.trim();
if name.is_empty() {
    eprintln!("plugin action requires a non-empty name");
    return;
}
// now safe: app.plugin(format!("plugin {name}"))

Type guard

fn valid_plugin_name(s: Option<&str>) -> bool {
    s.map(|s| !s.is_empty()).unwrap_or(false)
}

Prevention

Always quote the plugin name in keymap run strings: `plugin my-plugin`.
Verify dynamic plugin names with a non-empty check before dispatching.
Prefer the `plugin` action form with the name as the first argument, args after `--`.

When it happens

Trigger: Emitting or dispatching a `plugin` action whose first argument (`a.take_first::<SStr>()`) is absent or the empty string, e.g. `plugin ''` or an action built with no args.

Common situations: Keymap entries like `{ on = 'p', run = 'plugin' }` missing the plugin name, shell-style quoting errors that collapse the argument, or dynamic plugin names computed at runtime that end up empty.

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@5f901b886b (2026-09-02). Data as JSON: /api/errors/4dda6ed04bd9ca97. Report an issue: GitHub.