{"record":{"id":"fe5929f6ebdd9007","repo":"NousResearch/hermes-agent","slug":"noun-looks-corrupted-checksum-mismatch","errorCode":null,"errorMessage":"${Noun} looks corrupted (checksum mismatch).","messagePattern":"(.+?) looks corrupted \\(checksum mismatch\\)\\.","errorType":"exception","errorClass":"LoadoutError","httpStatus":null,"severity":"warning","filePath":"apps/desktop/src/lib/loadout.ts","lineNumber":268,"sourceCode":"      throw new Err(`That doesn't look like a ${noun}.`)\n    }\n\n    if (framed.length <= HEAD_BYTES) {\n      throw new Err(`${Noun} is too short to be valid.`)\n    }\n\n    const head = new BitReader(framed.subarray(0, HEAD_BYTES))\n    const version = head.uint(8)\n    const storedSum = head.uint(16)\n\n    if (version !== spec.version) {\n      throw new Err(`${Noun} is version ${version}; this build reads version ${spec.version}.`)\n    }\n\n    const payload = framed.subarray(HEAD_BYTES)\n\n    if (checksum16(payload) !== storedSum) {\n      throw new Err(`${Noun} looks corrupted (checksum mismatch).`)\n    }\n\n    try {\n      return spec.read(new BitReader(inflateSync(payload)))\n    } catch (err) {\n      throw new Err(err instanceof Error ? `${Noun} is malformed: ${err.message}` : `${Noun} is malformed.`)\n    }\n  }\n\n  return { decode, encode }\n}\n","sourceCodeStart":250,"sourceCodeEnd":280,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/apps/desktop/src/lib/loadout.ts#L250-L280","documentation":"Thrown by the loadout codec's decode() in apps/desktop/src/lib/loadout.ts:268 when the 16-bit checksum stored in the frame header does not match checksum16() recomputed over the payload bytes. The frame is version(8 bits) + checksum(16 bits) + DEFLATE-compressed body; the checksum catches corruption between encode and decode — character loss/mutation in transit, a bad copy/paste, or bit rot — before inflate+schema parsing produces nonsense.","triggerScenarios":"A share code that lost or gained characters but still base64-decodes (checksum then fails); manual editing of a code; a transport layer that truncates or re-encodes part of the payload; producing codes with a checksum computed over different bytes than framed (encode bug).","commonSituations":"Clipboard truncation at a fixed length; messaging apps mangling long strings; users 'fixing' a code by typing; mismatched checksum function between producer and consumer builds.","solutions":["Re-copy the code from its source, unedited, and paste it whole (the codec already tolerates whitespace).","If it persists, regenerate the code at the producer — the payload itself may have been corrupted before hashing.","Verify producer and consumer use the same checksum16 and the same header layout/version.","Treat this as data corruption, not a schema problem — do not try to decode past it."],"exampleFix":"// not a code fix — corruption is in the data, not the call site.\n// Producer-side round-trip assertion to catch bad encoders early:\nconst code = encode(payload)\nconst back = decode(code) // assert deep-equals payload before shipping the codec change","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { const v = decode(code) } catch (e) { if (e instanceof Err && /checksum mismatch/.test(e.message)) { promptRecopyOrRegenerate(); return null } throw e }","preventionTips":["Copy codes from source, unedited; the codec strips whitespace itself","Round-trip test producers so checksum coverage matches framed bytes","Never retry a checksum failure with modified input — it signals real corruption","Watch for clipboard managers truncating long strings"],"tags":["desktop","loadout","checksum","corruption","share-codes"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}