journal restore error: failed to renumber descriptor (from={

Error message

journal restore error: failed to renumber descriptor (from={}, to={}) - {}

What it means

apply_fd_renumber replays an FdRenumber journal entry by calling fd_renumber_internal(from, to); any result other than Errno::Success raises this error. It means a descriptor could not be moved from `from` to `to`, leaving the restored fd table inconsistent with the snapshot.

Source

Thrown at lib/wasix/src/journal/effector/syscalls/fd_renumber.rs:25

        to: Fd,
    ) -> anyhow::Result<()> {
        Self::save_event(
            ctx,
            JournalEntry::RenumberFileDescriptorV1 {
                old_fd: from,
                new_fd: to,
            },
        )
    }

    pub fn apply_fd_renumber(
        ctx: &mut FunctionEnvMut<'_, WasiEnv>,
        from: Fd,
        to: Fd,
    ) -> anyhow::Result<()> {
        let ret = crate::syscalls::fd_renumber_internal(ctx, from, to);
        if !matches!(ret, Ok(Errno::Success)) {
            bail!(
                "journal restore error: failed to renumber descriptor (from={}, to={}) - {}",
                from,
                to,
                ret.unwrap_or(Errno::Unknown)
            );
        }
        Ok(())
    }
}

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Regenerate the snapshot and retry the restore.
Ensure preopen/mount configuration matches between capture and restore environments.
Verify journal ordering and completeness.
Align runtime versions between snapshot and restore.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: both fds must be renamable per the snapshot's fd table
let ok = journal.renumber_entries().iter().all(|r|
    env.fd_exists(r.from) && (env.fd_free(r.to) || env.fd_removable(r.to))
);
if !ok { return Err(anyhow::anyhow!("fd renumber preconditions not met; align env with snapshot")); }

Try / catch

match restore_from_journal(&env, &journal) {
    Err(e) if e.to_string().contains("failed to renumber descriptor") => {
        eprintln!("renumber failed: {e}; rebuilding env from fresh snapshot");
        resume_with_fresh_snapshot()?;
    }
    other => other?,
}

Prevention

Replay journals strictly in original order.
Match preopens and fd layout between capture and restore.
Pin the runtime version across snapshot/restore.

When it happens

Trigger: Journal restore replaying an FdRenumber entry where `from` doesn't exist, `to` is occupied by a non-removable/preopen descriptor, or the internal renumber returns an errno (e.g. Badf, Notcapable).

Common situations: Restoring into an environment with different preopened fds; journals replayed out of order; snapshot/restore across different runtime versions.

Related errors

AI-assisted analysis of wasmerio/wasmer@8c4b9ee9d3 (2026-09-01). Data as JSON: /api/errors/3163d9ca5f8d9b01. Report an issue: GitHub.