{"record":{"id":"a304bff855b93b8c","repo":"FuelLabs/fuels-ts","slug":"invalid-checksum","errorCode":"INVALID_CHECKSUM","errorMessage":"Checksum validation failed for the provided mnemonic.","messagePattern":"Checksum validation failed for the provided mnemonic\\.","errorType":"validation","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/account/src/mnemonic/utils.ts","lineNumber":93,"sourceCode":"        ErrorCode.INVALID_MNEMONIC,\n        `Invalid mnemonic: the word '${words[i]}' is not found in the provided wordlist.`\n      );\n    }\n\n    for (let bit = 0; bit < 11; bit += 1) {\n      if (index & (1 << (10 - bit))) {\n        entropy[offset >> 3] |= 1 << (7 - (offset % 8));\n      }\n      offset += 1;\n    }\n  }\n  const entropyBits = (32 * words.length) / 3;\n  const checksumBits = words.length / 3;\n  const checksumMask = getUpperMask(checksumBits);\n  const checksum = arrayify(sha256(entropy.slice(0, entropyBits / 8)))[0] & checksumMask;\n\n  if (checksum !== (entropy[entropy.length - 1] & checksumMask)) {\n    throw new FuelError(\n      ErrorCode.INVALID_CHECKSUM,\n      'Checksum validation failed for the provided mnemonic.'\n    );\n  }\n\n  return entropy.slice(0, entropyBits / 8);\n}\n","sourceCodeStart":75,"sourceCodeEnd":101,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/account/src/mnemonic/utils.ts#L75-L101","documentation":"Thrown by mnemonicWordsToEntropy when the BIP-39 checksum embedded in the last word(s) of the mnemonic does not match the SHA-256 checksum computed over the recovered entropy. A checksum failure means the phrase is internally inconsistent — almost always a typo, transposition, or wrong word — even if every word individually exists in the wordlist.","triggerScenarios":"Calling mnemonicToEntropy on a phrase where one word was substituted for another valid word (so error 103 does not fire); words swapped in order; a word count whose checksum bit-slicing is off; phrase assembled from two different valid phrases.","commonSituations":"User transposed two words (e.g. positions 3 and 4 swapped); a single word is a valid BIP-39 word but the wrong one for this phrase; phrase was reconstructed from memory and is slightly off; using a phrase generated by a different/buggy tool with a non-standard checksum.","solutions":["Compare the phrase against the original recorded seed phrase character-by-character; the error is almost always a wrong or transposed word.","Use a BIP-39 mnemonic checker to locate the offending word; try the ~2048 candidate words at each position if the rest is trusted.","If the phrase was generated elsewhere, re-generate it from its source entropy rather than hand-editing.","Ensure you are not accidentally dropping the final checksum word when copying."],"exampleFix":"// before — last word is wrong, so checksum fails\nMnemonic.mnemonicToEntropy('abandon ability abandon about above absent absent acid');\n\n// after — recover from the original entropy instead of guessing words\nconst entropy = Mnemonic.mnemonicToEntropy(originalCorrectPhrase);\n// or re-generate from known-good entropy\nconst phrase = Mnemonic.entropyToMnemonic(originalEntropy);","handlingStrategy":"try-catch","validationCode":"// There is no purely local checksum validator in the public API; rely on the SDK.\n// Pre-check that all words are valid (see error 103) so checksum is the only remaining failure.\nnull","typeGuard":"function isLikelyValidMnemonic(words: string[], wordlist: string[]): boolean {\n  // cheap pre-check: correct count + all words known; full checksum still needs the SDK\n  return [12,15,18,21,24].includes(words.length)\n    && words.every(w => wordlist.includes(w.normalize('NFKD')));\n}","tryCatchPattern":"import { FuelError, ErrorCode } from '@fuel-ts/errors';\ntry {\n  const entropy = mnemonicWordsToEntropy(words, wordlist);\n} catch (e) {\n  if (e instanceof FuelError && e.code === ErrorCode.INVALID_CHECKSUM) {\n    // phrase is internally inconsistent — ask user to re-enter the original\n  }\n  throw e;\n}","preventionTips":["Store the seed phrase verbatim; do not retype it.","Treat a checksum failure as a wrong/transposed word, not a network issue.","Keep the source entropy to regenerate the phrase if needed."],"tags":["mnemonic","bip39","checksum","wallet","validation"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}