sxyazi/yazi · error

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

Error message

Incompatible version (Ya {}, Yazi {}). Restart all `ya` and `yazi` processes if you upgraded either.

What it means

`Shot::ensure_version` compares the version string reported by the peer's handshake (`hey.version`) with the local `yazi_version::version()`. On any mismatch — or when the peer reports no version — it bails, warning that `ya` and `yazi` must be restarted after an upgrade because their protocol payloads are version-locked.

Source

Thrown at yazi-cli/src/dds/shot.rs:49

			match line.split(',').next() {
				Some("hey") => {
					if let Ok(Ember::Hey(hey)) = Payload::from_str(&line).map(|p| p.body) {
						(peers, version) = (hey.peers, Some(hey.version));
					}
				}
				Some("bye") => break,
				_ => {}
			}
		}

		Self::ensure_version(version.as_deref())?;
		Self::ensure_ability(&peers, kind, receiver)?;
		Ok(())
	}

	pub(super) fn ensure_version(version: Option<&str>) -> Result<()> {
		if version != Some(yazi_version::version()) {
			bail!(
				"Incompatible version (Ya {}, Yazi {}). Restart all `ya` and `yazi` processes if you upgraded either.",
				yazi_version::version(),
				version.unwrap_or("Unknown")
			);
		}
		Ok(())
	}

	pub(super) fn ensure_ability(peers: &HashMap<Id, Peer>, kind: &str, receiver: Id) -> Result<()> {
		match (receiver, peers.get(&receiver).map(|p| p.able(kind))) {
			// Send to all receivers
			(Id::ZERO, _) if peers.is_empty() => {
				bail!("No receiver found. Check if any receivers are running.")
			}
			(Id::ZERO, _) if peers.values().all(|p| !p.able(kind)) => {
				bail!("No receiver has the ability to receive `{kind}` messages.")
			}
			(Id::ZERO, _) => Ok(()),

View on GitHub (pinned to 5f901b886b)

Solutions

1. Quit the running Yazi instance(s) and start the freshly installed binary so both sides report the same version.
2. Verify both binaries come from the same build: `ya --version` vs the running yazi's version.
3. If a version mismatch is intentional (dev/testing), rebuild one side to match the other.

Example fix

// before
# ya 25.5.1 talking to a still-running yazi 25.4.8 after an upgrade
$ ya pub-to ...
Error: Incompatible version (Ya 25.5.1, Yazi 25.4.8)...
// after
$ pkill yazi && yazi &   # restart yazi with the new build
$ ya pub-to ...

// shell: refuse to run when versions diverge
[ "$(ya --version | awk '{print $2}')" = "$(yazi --version | awk '{print $2}')" ] || { echo "version mismatch: restart yazi" >&2; exit 1; }

match Shot::ensure_version(hey.version.as_deref()) {
  Err(e) => { eprintln!("{e}; quitting yazi and restarting usually fixes this"); return; }
  Ok(()) => {}
}

When it happens

Trigger: Calling any `ya pub`/`ya call` against a Yazi process started from a different build than the `ya` binary; Yazi was upgraded (e.g. via `cargo yazi install`) while the old instance kept running; the peer omits the version (reported as `Unknown`).

Common situations: Upgrading Yazi in place without restarting the running instance; `ya` and `yazi` installed from different commits; multiple versions installed across PATH entries.

Related errors

• {}
• Unknown error
• Expected custom payload of kind `{reply_kind}`
• Connection closed before receiving reply
• No receiver found. Check if any receivers are running.

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