What causes "Invalid 'opt' in SpawnForm" in sxyazi/yazi?

Provide the SpawnOpt payload under key 'opt' when building the spawn action.

Invalid 'opt' in SpawnForm

Error message

Invalid 'opt' in SpawnForm

What it means

SpawnForm holds the options for spawning a task via the tasks subsystem. TryFrom<ActionCow> requires an 'opt' entry; if a.take_any("opt") returns None (missing key or wrong type) the error "Invalid 'opt' in SpawnForm" is raised. It fails fast when a spawn action reaches the parser without its typed SpawnOpt payload.

Solutions

Provide the SpawnOpt payload under key 'opt' when building the spawn action.
Verify the SpawnOpt struct/fields in yazi-parser/src/tasks/spawn.rs for your yazi version.
Use the high-level task spawn API (e.g. TASKS.spawn(...)) instead of raw ActionCow construction.
Update plugin/config emitters to match the current payload schema.

Example fix

// before
let a = ActionCow::from("tasks.spawn");
let form = SpawnForm::try_from(a)?; // Invalid 'opt' in SpawnForm
// after
let a = ActionCow::from(("tasks.spawn", SpawnOpt::default()));
let form = SpawnForm::try_from(a)?;

Defensive patterns

Strategy: validation

Validate before calling

if !action.has("opt") {
    anyhow::bail!("tasks.spawn requires SpawnOpt under 'opt'");
}
let form = SpawnForm::try_from(action)?;

Type guard

fn has_opt(a: &ActionCow) -> bool { a.has("opt") }

Try / catch

let form = SpawnForm::try_from(action)
    .with_context(|| "spawn action malformed: missing 'opt'")?;

Prevention

Spawn tasks via the high-level TASKS.spawn API, not raw ActionCow.
Always pair the spawn action with its SpawnOpt payload.
Re-verify payload shape after yazi upgrades in custom spawners.

When it happens

Trigger: Constructing a tasks.spawn ActionCow without 'opt', or with an 'opt' value not matching the expected SpawnOpt type so take_any fails.

Common situations: Custom task spawners in config/plugins emitting spawn manually; renamed or reshaped options after a yazi upgrade; the action forwarded with only its name and no payload.

Related errors

AI-assisted analysis of sxyazi/yazi@5f901b886b (2026-09-02). Data as JSON: /api/errors/7fe88ab8781c58da. Report an issue: GitHub.

Appendix: source

Thrown at yazi-parser/src/tasks/spawn.rs:15

use anyhow::anyhow;
use mlua::{ExternalError, FromLua, IntoLua, Lua, Value};
use yazi_core::tasks::TaskOpt;
use yazi_shared::event::ActionCow;

#[derive(Clone, Debug)]
pub struct SpawnForm {
	pub opt: TaskOpt,
}

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

	fn try_from(mut a: ActionCow) -> Result<Self, Self::Error> {
		Ok(Self { opt: a.take_any("opt").ok_or_else(|| anyhow!("Invalid 'opt' in SpawnForm"))? })
	}
}

impl FromLua for SpawnForm {
	fn from_lua(_: Value, _: &Lua) -> mlua::Result<Self> { Err("unsupported".into_lua_err()) }
}

impl IntoLua for SpawnForm {
	fn into_lua(self, _: &Lua) -> mlua::Result<Value> { Err("unsupported".into_lua_err()) }
}

View on GitHub (pinned to 5f901b886b)