FuelLabs/fuels-ts · error · FuelError

INVALID_CHECKSUM

INVALID_CHECKSUM

Error message

Checksum validation failed for the provided mnemonic.

What it means

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.

Source

Thrown at packages/account/src/mnemonic/utils.ts:93

        ErrorCode.INVALID_MNEMONIC,
        `Invalid mnemonic: the word '${words[i]}' is not found in the provided wordlist.`
      );
    }

    for (let bit = 0; bit < 11; bit += 1) {
      if (index & (1 << (10 - bit))) {
        entropy[offset >> 3] |= 1 << (7 - (offset % 8));
      }
      offset += 1;
    }
  }
  const entropyBits = (32 * words.length) / 3;
  const checksumBits = words.length / 3;
  const checksumMask = getUpperMask(checksumBits);
  const checksum = arrayify(sha256(entropy.slice(0, entropyBits / 8)))[0] & checksumMask;

  if (checksum !== (entropy[entropy.length - 1] & checksumMask)) {
    throw new FuelError(
      ErrorCode.INVALID_CHECKSUM,
      'Checksum validation failed for the provided mnemonic.'
    );
  }

  return entropy.slice(0, entropyBits / 8);
}

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Compare the phrase against the original recorded seed phrase character-by-character; the error is almost always a wrong or transposed word.
2. Use a BIP-39 mnemonic checker to locate the offending word; try the ~2048 candidate words at each position if the rest is trusted.
3. If the phrase was generated elsewhere, re-generate it from its source entropy rather than hand-editing.
4. Ensure you are not accidentally dropping the final checksum word when copying.

Example fix

// before — last word is wrong, so checksum fails
Mnemonic.mnemonicToEntropy('abandon ability abandon about above absent absent acid');

// after — recover from the original entropy instead of guessing words
const entropy = Mnemonic.mnemonicToEntropy(originalCorrectPhrase);
// or re-generate from known-good entropy
const phrase = Mnemonic.entropyToMnemonic(originalEntropy);

// There is no purely local checksum validator in the public API; rely on the SDK.
// Pre-check that all words are valid (see error 103) so checksum is the only remaining failure.
null

function isLikelyValidMnemonic(words: string[], wordlist: string[]): boolean {
  // cheap pre-check: correct count + all words known; full checksum still needs the SDK
  return [12,15,18,21,24].includes(words.length)
    && words.every(w => wordlist.includes(w.normalize('NFKD')));
}

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  const entropy = mnemonicWordsToEntropy(words, wordlist);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.INVALID_CHECKSUM) {
    // phrase is internally inconsistent — ask user to re-enter the original
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• INVALID_ENTROPY
• INVALID_MNEMONIC
• INVALID_SEED
• INVALID_MNEMONIC
• INVALID_WORD_LIST

AI-assisted analysis of FuelLabs/fuels-ts@b3f37c91ac (2026-08-12). Data as JSON: /api/errors/a304bff855b93b8c. Report an issue: GitHub.