copy/v86 · error · StateLoadError

Version mismatch: dump=... we=...

Error message

Version mismatch: dump=... we=...

What it means

State dumps record the STATE_VERSION they were written with in the header. read_state_header throws StateLoadError('Version mismatch: dump=N we=M') when the dump's version differs from the currently compiled STATE_VERSION, because internal state layouts are not guaranteed compatible across versions.

Source

Thrown at src/state.js:222

    function read_state_header(state, check_length)
    {
        const len = state.length;

        if(len < STATE_INFO_BLOCK_START)
        {
            throw new StateLoadError("Invalid length: " + len);
        }

        const header_block = new Int32Array(state.buffer, state.byteOffset, 4);

        if(header_block[STATE_INDEX_MAGIC] !== STATE_MAGIC)
        {
            throw new StateLoadError("Invalid header: " + h(header_block[STATE_INDEX_MAGIC] >>> 0));
        }

        if(header_block[STATE_INDEX_VERSION] !== STATE_VERSION)
        {
            throw new StateLoadError(
                    "Version mismatch: dump=" + header_block[STATE_INDEX_VERSION] +
                    " we=" + STATE_VERSION);
        }

        if(check_length && header_block[STATE_INDEX_TOTAL_LEN] !== len)
        {
            throw new StateLoadError(
                    "Length doesn't match header: " +
                    "real=" + len + " header=" + header_block[STATE_INDEX_TOTAL_LEN]);
        }

        return header_block[STATE_INDEX_INFO_LEN];
    }

    function read_info_block(info_block_buffer)
    {
        const info_block = new TextDecoder().decode(info_block_buffer);
        return JSON.parse(info_block);

View on GitHub (pinned to 180830d539)

Solutions

1. Load states only with the same emulator version that produced them (pin the library version alongside saved states)
2. Re-create the state with the current emulator version instead of restoring the old dump
3. Store the emulator version with each saved state and check it in your app before calling restore_state
4. If you control the build, regenerate states after upgrades and invalidate old ones

Example fix

// before
const state = localStorage.getItem("vmstate");
emulator.restore_state(JSON.parse(state));
// after
const saved = JSON.parse(localStorage.getItem("vmstate"));
if (saved.v86Version !== CURRENT_V86_VERSION) {
    alert("Saved state is from an older version; please restart the VM.");
} else {
    emulator.restore_state(new Uint8Array(saved.state));
}

function stateVersionMatches(buf, expected = STATE_VERSION) {
    const v = new Int32Array(buf.buffer, buf.byteOffset, 4)[1];
    return v === expected;
}
if (!stateVersionMatches(state))
    alert("State was saved with a different emulator version; start a new VM instead.");

try {
    emulator.restore_state(state);
} catch (e) {
    if (e instanceof StateLoadError && /Version mismatch/.test(e.message)) {
    const dumpV = parseInt((e.message.match(/dump=(\d+)/) || [])[1], 10);
    offerStateUpgradeOrRestart(dumpV);
    } else throw e;
}

When it happens

Trigger: Calling restore_state with a state file created by a different version of v86/emulator code than the one performing the restore — e.g. old saved state loaded into an updated emulator bundle, or vice versa.

Common situations: Application updated the v86 library but users still have states saved by the previous version; loading states shared between users running different builds; CDN serving a newer emulator JS while an older cached state is restored.

Related errors

• Invalid length:
• Invalid header:
• Length doesn't match header: real=... header=...
• Invalid info block length:

AI-assisted analysis of copy/v86@180830d539 (2026-08-31). Data as JSON: /api/errors/3d00e9d7d36591f1. Report an issue: GitHub.