{"record":{"id":"4018a09ecd8e5bad","repo":"sxyazi/yazi","slug":"plugin-name-requires-at-least-yazi-but-you","errorCode":null,"errorMessage":"Plugin `{name}` requires at least Yazi {}, but your current version is Yazi {}.","messagePattern":"Plugin `(.+?)` requires at least Yazi (.+?), but your current version is Yazi (.+?)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"yazi-runner/src/loader/loader.rs","lineNumber":180,"sourceCode":"\n\t\tlet t: Table = lua.load(chunk).set_name(name).call(())?;\n\t\tt.raw_set(\"_id\", lua.create_string(name)?)?;\n\n\t\tloaded.raw_set(name, t.clone())?;\n\t\tOk(t)\n\t}\n\n\tpub fn try_load(&self, lua: &Lua, name: &str) -> mlua::Result<Table> {\n\t\tlet (name, ..) = Self::explode_name_parts(name)?;\n\t\tlua.globals().raw_get::<Table>(\"package\")?.raw_get::<Table>(\"loaded\")?.raw_get(name)\n\t}\n\n\tpub fn compatible_or_error(name: &str, chunk: &Chunk) -> Result<()> {\n\t\tif chunk.compatible() {\n\t\t\treturn Ok(());\n\t\t}\n\n\t\tbail!(\n\t\t\t\"Plugin `{name}` requires at least Yazi {}, but your current version is Yazi {}.\",\n\t\t\tchunk.since,\n\t\t\tyazi_version::version_long()\n\t\t);\n\t}\n\n\tfn explode_name_parts(name: &str) -> anyhow::Result<(&str, &str, &str)> {\n\t\tlet name = name.strip_suffix(\".main\").unwrap_or(name);\n\t\tlet (plugin, entry) =\n\t\t\tif let Some((a, b)) = name.split_once(\".\") { (a, b) } else { (name, \"main\") };\n\n\t\tensure!(plugin.as_bytes().kebab_cased(), \"Plugin name `{plugin}` must be in kebab-case\");\n\t\tensure!(entry.as_bytes().kebab_cased(), \"Entry name `{entry}` must be in kebab-case\");\n\t\tOk((name, plugin, entry))\n\t}\n}\n","sourceCodeStart":162,"sourceCodeEnd":197,"githubUrl":"https://github.com/sxyazi/yazi/blob/8ebf930f1796ae2076b7d6b0c5e93a1002c18134/yazi-runner/src/loader/loader.rs#L162-L197","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Upgrade Yazi to at least the version the plugin requires (e.g. `cargo install yazi-fm yazi-cli` or your package manager)","Downgrade the plugin to a release whose `since` is <= your Yazi version","Check the plugin's `since` value in its Header and compare with `yazi --version`"],"exampleFix":"-- plugin main.lua Header\n-- before\nsince = 25.5.28\n-- after (if you cannot upgrade Yazi)\nsince = 25.2.7","handlingStrategy":"type-guard","validationCode":"local min_since = plugin.Header.since\nif min_since and min_since > YAZI_VERSION then\n  print(\"plugin requires Yazi \" .. min_since .. \", you have \" .. YAZI_VERSION)\n  return\nend","typeGuard":"fn plugin_compatible(since: Version) -> bool { since <= yazi_version::version() }","tryCatchPattern":"// Rust\nif let Err(e) = Loader::compatible_or_error(name, &chunk) {\n  tracing::warn!(\"skipping plugin {name}: {e}\");\n  return;\n}","preventionTips":["Keep Yazi updated alongside plugins","Read each plugin's README for its minimum Yazi version","Compare `yazi --version` with the plugin Header `since` after updates","Pin plugin versions compatible with distro-packaged Yazi"],"tags":["versioning","plugin-loader","compatibility"],"backgroundTag":"plugin-version-incompatible","analyzedSha":"8ebf930f1796ae2076b7d6b0c5e93a1002c18134","analyzedAt":"2026-09-02T18:38:25.566Z","contentChangedAt":"2026-09-02T18:38:25.566Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}