{"record":{"id":"668f32a398576ef5","repo":"copy/v86","slug":"invalid-header","errorCode":null,"errorMessage":"Invalid header: ","messagePattern":"Invalid header: ","errorType":"exception","errorClass":"StateLoadError","httpStatus":null,"severity":"error","filePath":"src/state.js","lineNumber":217,"sourceCode":"/* @param {CPU} cpu */\nexport function restore_state(cpu, state)\n{\n    state = new Uint8Array(state);\n\n    function read_state_header(state, check_length)\n    {\n        const len = state.length;\n\n        if(len < STATE_INFO_BLOCK_START)\n        {\n            throw new StateLoadError(\"Invalid length: \" + len);\n        }\n\n        const header_block = new Int32Array(state.buffer, state.byteOffset, 4);\n\n        if(header_block[STATE_INDEX_MAGIC] !== STATE_MAGIC)\n        {\n            throw new StateLoadError(\"Invalid header: \" + h(header_block[STATE_INDEX_MAGIC] >>> 0));\n        }\n\n        if(header_block[STATE_INDEX_VERSION] !== STATE_VERSION)\n        {\n            throw new StateLoadError(\n                    \"Version mismatch: dump=\" + header_block[STATE_INDEX_VERSION] +\n                    \" we=\" + STATE_VERSION);\n        }\n\n        if(check_length && header_block[STATE_INDEX_TOTAL_LEN] !== len)\n        {\n            throw new StateLoadError(\n                    \"Length doesn't match header: \" +\n                    \"real=\" + len + \" header=\" + header_block[STATE_INDEX_TOTAL_LEN]);\n        }\n\n        return header_block[STATE_INDEX_INFO_LEN];\n    }","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/copy/v86/blob/180830d539dcc87db1a191febf6c914f516d102f/src/state.js#L199-L235","documentation":"After the length check, read_state_header reads the 4-int header block and compares the magic number at STATE_INDEX_MAGIC against STATE_MAGIC. A mismatch means the buffer is not a v86 state dump at all, so StateLoadError('Invalid header: 0x...') is thrown with the observed magic in hex.","triggerScenarios":"Loading a file that isn't a v86 state dump (wrong file type, foreign save format, text/HTML error page) into restore_state; loading a state produced by an incompatible emulator build that wrote a different magic.","commonSituations":"Users picking the wrong file in a file picker (a ROM or disk image instead of a state); proxy/server error responses saved as .bin; crossing major versions where the state format's magic changed.","solutions":["Verify you're passing a v86 save-state file (correct extension and origin) to restore_state","Re-create the state with the same emulator version used for loading","Check the served file isn't an error page: inspect the first bytes / content-length","If migrating formats, convert or re-capture the state rather than loading old binaries"],"exampleFix":"// before\nemulator.restore_state(await file.arrayBuffer().then(b => new Uint8Array(b))); // any file accepted\n// after\nconst view = new Int32Array(buf);\nif (view[0] !== MAGIC) { // 0x8601CCE0-style state magic\n    throw new Error(\"not a v86 state file\");\n}\nemulator.restore_state(new Uint8Array(buf));","handlingStrategy":"validation","validationCode":"function looksLikeV86State(buf) {\n    if (!(buf instanceof Uint8Array) || buf.byteLength < 12) return false;\n    const magic = new Int32Array(buf.buffer, buf.byteOffset, 4)[0] >>> 0;\n    return magic === STATE_MAGIC; // same constant as src/state.js\n}\nif (!looksLikeV86State(state)) throw new Error(\"not a v86 state file\");","typeGuard":"function isV86StateDump(x) {\n    return x instanceof Uint8Array && x.byteLength >= 12 &&\n    (new Int32Array(x.buffer, x.byteOffset, 4)[0] >>> 0) === STATE_MAGIC;\n}","tryCatchPattern":"try {\n    emulator.restore_state(state);\n} catch (e) {\n    if (e instanceof StateLoadError && /Invalid header/.test(e.message)) {\n    showError(\"That file is not a v86 save state.\");\n    } else throw e;\n}","preventionTips":["Filter file pickers to the correct state extension","Check magic bytes before restore","Label state files clearly so users pick the right one","Don't persist error pages as state files"],"tags":["state","validation","file-format"],"backgroundTag":"state-load-failed","analyzedSha":"180830d539dcc87db1a191febf6c914f516d102f","analyzedAt":"2026-08-31T22:39:37.599Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}