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

Validate the command string is non-empty and contains a real first token before parsing.

command name cannot be empty

Error message

command name cannot be empty

What it means

`Cmd::from_str` parses a command string by shell-splitting it (respecting quotes and an optional trailing `last` word). If the split yields no words, or the first word is empty (e.g. the string was empty or started with whitespace/quotes producing an empty name), it bails with "command name cannot be empty".

Source

Thrown at yazi-shared/src/event/cmd.rs:23

use mlua::{UserData, UserDataFields};
use serde_with::DeserializeFromStr;
use yazi_shim::{SStr, mlua::UserDataFieldsExt};

use crate::{data::{Data, DataKey}, sendable::Sendable};

#[derive(Clone, Debug, Default, DeserializeFromStr)]
pub struct Cmd {
	pub name: SStr,
	pub args: HashMap<DataKey, Data>,
}

impl FromStr for Cmd {
	type Err = anyhow::Error;

	fn from_str(s: &str) -> Result<Self, Self::Err> {
		let (mut words, last) = crate::shell::unix::split(s, true)?;
		if words.is_empty() || words[0].is_empty() {
			bail!("command name cannot be empty");
		}

		Ok(Self {
			name: mem::take(&mut words[0]).into(),
			args: Self::parse_args(words.into_iter().skip(1), last)?,
		})
	}
}

impl Cmd {
	pub(crate) fn null() -> Self { Self { name: "null".into(), ..Default::default() } }

	pub fn parse_args<I>(words: I, last: Option<String>) -> Result<HashMap<DataKey, Data>>
	where
		I: IntoIterator<Item = String>,
	{
		let mut i = 0i64;
		words

View on GitHub (pinned to 8ebf930f17)

Solutions

Validate the command string is non-empty and contains a real first token before parsing.
Fix the config/keymap entry so `run` (or equivalent) names a command, e.g. `run = 'arrow -1'`.
Trim whitespace before parsing and reject blank input at the boundary.
Check the shell split behavior if your command starts with quotes — ensure the command name is not quoted empty.

Example fix

// before
let cmd: Cmd = user_input.parse()?; // user_input = "" or "   "
// after
let s = user_input.trim();
anyhow::ensure!(!s.is_empty(), "command string is empty");
let cmd: Cmd = s.parse()?;

Defensive patterns

Strategy: validation

Validate before calling

fn valid_cmd(s: &str) -> bool {
    let first = s.split_whitespace().next();
    matches!(first, Some(w) if !w.is_empty())
}

Try / catch

let cmd: Cmd = user_input.trim().parse().map_err(|e| {
    tracing::error!("bad command {user_input:?}: {e}");
    e
})?;

Prevention

Trim and non-empty check command strings before parsing.
In keymap.toml, ensure every `run` value names a command.
Validate dynamic command builders: the first token must be a known command.
Avoid leading quotes/whitespace that can yield an empty first word.

When it happens

Trigger: Parsing an empty string with `"".parse::<Cmd>()`; parsing a string of only whitespace; a quoting quirk where `split` returns `""` as words[0]; keymap/config entries whose command value is blank or unquoted-empty.

Common situations: Yazi keymap.toml / config where a `run` value is empty or only spaces; dynamically built command strings where a variable that should hold the command name is empty; plugins constructing Cmd from user input that was never validated.

Related errors

AI-assisted analysis of sxyazi/yazi@8ebf930f17 (2026-09-02). Data as JSON: /api/errors/d195da84a0bd6b5a. Report an issue: GitHub.