{"record":{"id":"391e57c81692e3c9","repo":"NousResearch/hermes-agent","slug":"noun-is-malformed-err-message","errorCode":null,"errorMessage":"${Noun} is malformed: ${err.message}","messagePattern":"(.+?) is malformed: (.+?)","errorType":"exception","errorClass":"LoadoutError","httpStatus":null,"severity":"warning","filePath":"apps/desktop/src/lib/loadout.ts","lineNumber":274,"sourceCode":"\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":256,"sourceCodeEnd":280,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/apps/desktop/src/lib/loadout.ts#L256-L280","documentation":"Thrown by the loadout codec's decode() in apps/desktop/src/lib/loadout.ts:274 when the payload passes version and checksum but fails during inflation (inflateSync) or schema reading (spec.read over BitReader) — the exception's message is appended as '<Noun> is malformed: <reason>'. This catches payloads that are structurally intact per the frame but semantically broken: invalid DEFLATE streams, bit-reads running past the end ('loadout truncated' RangeError gets wrapped here), or schema-level constraint violations inside spec.read.","triggerScenarios":"spec.read throwing its own validation errors (e.g. unknown enum id, out-of-range index); BitReader running off the end because read/write schemas disagree at the current version; inflateSync failing on a payload that checksummed correctly but was produced by a buggy writer.","commonSituations":"A producer bug writing fewer bits than read consumes while still bumping neither version nor catching the mismatch; schema changes shipped with a version bump but an asymmetric read; codes generated by experimental builds.","solutions":["Read the appended inner message — it identifies whether inflation or a specific schema read failed and usually names the field.","Round-trip test encode()->decode() for every spec change; a malformed-code error from your own producer is a writer/reader asymmetry bug.","Ensure spec.read validates its own invariants (throw with a descriptive message) so this error is precise.","For user-pasted codes, request a fresh code; this stage means the bytes are self-consistent but wrong-shaped."],"exampleFix":"// before — read consumes more than write emits (surfaces as 'malformed: loadout truncated')\nwrite: (w, v) => { w.str(v.name) }\nread: r => ({ name: r.str(), extra: r.uint(3) }) // extra never written\n\n// after — symmetric schema\nwrite: (w, v) => { w.str(v.name); w.uint(v.extra ?? 0, 3) }\nread: r => ({ name: r.str(), extra: r.uint(3) })","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"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// callers: catch (e) { if (e instanceof Err && /malformed/.test(e.message)) requestFreshCode() }","preventionTips":["Log the inner message — it pinpoints the failing schema read","Throw descriptive errors from spec.read's own validation so wrapped messages are actionable","Round-trip test encode/decode for every schema edit","Malformed-after-checksum usually means a buggy producer build — collect the code's origin before regenerating"],"tags":["desktop","loadout","codec","schema","validation"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}