sxyazi/yazi · error

Plugin `{name}` requires at least Yazi {}, but your current

Error message

Plugin `{name}` requires at least Yazi {}, but your current version is Yazi {}.

What it means

Each Lua plugin declares a `since` version in its Chunk metadata stating the minimum Yazi version it targets. `compatible_or_error` compares that with the running Yazi version (`yazi_version::version_long()`) and errors when the plugin requires a newer Yazi than the one installed, preventing incompatibilities from surfacing as cryptic runtime failures.

Source

Thrown at yazi-runner/src/loader/loader.rs:180

		let t: Table = lua.load(chunk).set_name(name).call(())?;
		t.raw_set("_id", lua.create_string(name)?)?;

		loaded.raw_set(name, t.clone())?;
		Ok(t)
	}

	pub fn try_load(&self, lua: &Lua, name: &str) -> mlua::Result<Table> {
		let (name, ..) = Self::explode_name_parts(name)?;
		lua.globals().raw_get::<Table>("package")?.raw_get::<Table>("loaded")?.raw_get(name)
	}

	pub fn compatible_or_error(name: &str, chunk: &Chunk) -> Result<()> {
		if chunk.compatible() {
			return Ok(());
		}

		bail!(
			"Plugin `{name}` requires at least Yazi {}, but your current version is Yazi {}.",
			chunk.since,
			yazi_version::version_long()
		);
	}

	fn explode_name_parts(name: &str) -> anyhow::Result<(&str, &str, &str)> {
		let name = name.strip_suffix(".main").unwrap_or(name);
		let (plugin, entry) =
			if let Some((a, b)) = name.split_once(".") { (a, b) } else { (name, "main") };

		ensure!(plugin.as_bytes().kebab_cased(), "Plugin name `{plugin}` must be in kebab-case");
		ensure!(entry.as_bytes().kebab_cased(), "Entry name `{entry}` must be in kebab-case");
		Ok((name, plugin, entry))
	}
}

View on GitHub (pinned to 8ebf930f17)

Solutions

1. Upgrade Yazi to at least the version the plugin requires (e.g. `cargo install yazi-fm yazi-cli` or your package manager)
2. Downgrade the plugin to a release whose `since` is <= your Yazi version
3. Check the plugin's `since` value in its Header and compare with `yazi --version`

Example fix

-- plugin main.lua Header
-- before
since = 25.5.28
-- after (if you cannot upgrade Yazi)
since = 25.2.7

local min_since = plugin.Header.since
if min_since and min_since > YAZI_VERSION then
  print("plugin requires Yazi " .. min_since .. ", you have " .. YAZI_VERSION)
  return
end

fn plugin_compatible(since: Version) -> bool { since <= yazi_version::version() }

// Rust
if let Err(e) = Loader::compatible_or_error(name, &chunk) {
  tracing::warn!("skipping plugin {name}: {e}");
  return;
}

When it happens

Trigger: Installing/upgrading a plugin whose `since` (in its main.lua Header/Chunk) is greater than the running Yazi version, then Yazi loads that plugin at startup or first use.

Common situations: Plugin README says 'requires Yazi 25.x' but the user runs an older yazi binary; distro-packaged yazi lagging behind plugin releases; partial yazi upgrade (new config/plugins, old binary).

Related errors

• Incompatible version (Ya {}, Yazi {}). Restart all `ya` and

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