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

Attach the ProcessOpenOpt payload under key 'opt' when constructing the action.

Invalid 'opt' in ProcessOpenForm

Error message

Invalid 'opt' in ProcessOpenForm

What it means

ProcessOpenForm starts processing an opened file's data and requires an 'opt' payload (the process-open options, including how to reply). Its TryFrom<ActionCow> raises "Invalid 'opt' in ProcessOpenForm" when a.take_any("opt") returns None. The replier is taken separately and optional; only 'opt' is mandatory.

Solutions

Attach the ProcessOpenOpt payload under key 'opt' when constructing the action.
Check the Opt struct in yazi-parser/src/tasks/process_open.rs for your version and align types.
Route process-open through the tasks subsystem's normal open flow so 'opt' is attached automatically.
Update any out-of-tree emitters after upgrading yazi.

Example fix

// before
let a = ActionCow::from("tasks.process-open"); // missing opt
// after
let a = ActionCow::from(("tasks.process-open", ProcessOpenOpt::default()));

Defensive patterns

Strategy: validation

Validate before calling

if !action.has("opt") {
    anyhow::bail!("tasks.process-open requires ProcessOpenOpt under 'opt'");
}
let form = ProcessOpenForm::try_from(action)?;

Type guard

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

Try / catch

let form = ProcessOpenForm::try_from(action)
    .context("process-open dispatched without 'opt'")?;

Prevention

Use the tasks open flow to generate process-open instead of hand-building it.
Attach ProcessOpenOpt explicitly when testing task processing directly.
Remember 'replier' is optional; only 'opt' is required.

When it happens

Trigger: Dispatching tasks.process-open without an 'opt' field, or with an 'opt' value whose type cannot be taken as the expected ProcessOpenOpt.

Common situations: Custom plugin/emitter code building process-open manually; a yazi update changing the options struct so stored values no longer type-match; payload lost when relaying the action.

Related errors

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

Appendix: source

Thrown at yazi-parser/src/tasks/process_open.rs:17

use anyhow::anyhow;
use mlua::{ExternalError, FromLua, IntoLua, Lua, Value};
use yazi_scheduler::process::ShellOpt;
use yazi_shared::event::{ActionCow, Replier};

#[derive(Clone, Debug)]
pub struct ProcessOpenForm {
	pub opt:     ShellOpt,
	pub replier: Option<Replier>,
}

impl TryFrom<ActionCow> for ProcessOpenForm {
	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 ProcessOpenForm"))?,
			replier: a.take_replier(),
		})
	}
}

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

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

View on GitHub (pinned to 5f901b886b)