NousResearch/hermes-agent · warning · LoadoutError

${Noun} is version ${version}; this build reads version ${sp

Error message

${Noun} is version ${version}; this build reads version ${spec.version}.

What it means

Thrown by the loadout codec's decode() in apps/desktop/src/lib/loadout.ts:262 when the 8-bit version in the frame header does not equal the current spec.version. Every loadout spec versions its bit layout precisely so old codes fail this explicit, readable check instead of misreading bits (which would produce garbage or the 'loadout truncated' RangeError). The message names both the code's version and the version this build reads.

Source

Thrown at apps/desktop/src/lib/loadout.ts:262

    let framed: Uint8Array

    try {
      framed = fromBase64Url(raw)
    } catch {
      throw new Err(`That doesn't look like a ${noun}.`)
    }

    if (framed.length <= HEAD_BYTES) {
      throw new Err(`${Noun} is too short to be valid.`)
    }

    const head = new BitReader(framed.subarray(0, HEAD_BYTES))
    const version = head.uint(8)
    const storedSum = head.uint(16)

    if (version !== spec.version) {
      throw new Err(`${Noun} is version ${version}; this build reads version ${spec.version}.`)
    }

    const payload = framed.subarray(HEAD_BYTES)

    if (checksum16(payload) !== storedSum) {
      throw new Err(`${Noun} looks corrupted (checksum mismatch).`)
    }

    try {
      return spec.read(new BitReader(inflateSync(payload)))
    } catch (err) {
      throw new Err(err instanceof Error ? `${Noun} is malformed: ${err.message}` : `${Noun} is malformed.`)
    }
  }

  return { decode, encode }
}

View on GitHub (pinned to c896c09c42)

Solutions

1. Regenerate the share code on the current build and share the new one.
2. If you changed the layout in spec code, bump spec.version in the same commit — that is the whole mechanism.
3. To support old codes, keep parallel read specs keyed by version and dispatch after parsing the header.
4. Update the receiving app to a build whose spec.version matches the code's producer.

Example fix

// before — layout changed, version not bumped: old codes decode as garbage
write: w => { w.uint(mode, 2); w.uint(flags, 4) }

// after — bump version with any layout change
export const skillsSpec = createLoadout({
  version: 2,
  // ...
})

// producer/consumer agreement check in dev builds
if (spec.version !== EXPECTED_SHARE_VERSION) throw new Error('codec/spec version drift — bump together')

try { const v = decode(code) } catch (e) {
  if (e instanceof Err && /version/.test(e.message)) { promptRegenerateCode(); return null }
  throw e
}

When it happens

Trigger: Decoding a code produced by an older build whose spec.version was lower; decoding a code from a NEWER build (version higher than local); forgetting to bump spec.version after changing the read/write schema, so old codes shift into misalignment instead of failing here.

Common situations: Sharing codes across app versions or with teammates on older releases; schema evolution (a field added/removed/resized) without a version bump; archived codes pasted after a format change.

Related errors

• That doesn't look like a ${noun}.
• ${Noun} is too short to be valid.
• ${Noun} looks corrupted (checksum mismatch).
• ${Noun} is malformed: ${err.message}
• loadout truncated

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/7712b5c17fe0d9a3. Report an issue: GitHub.