FuelLabs/fuels-ts · error · FuelError

INVALID_MNEMONIC

INVALID_MNEMONIC

Error message

Invalid mnemonic size. Expected one of [${MNEMONIC_SIZES.join(', ')}] words, but got ${words.length}.

What it means

Thrown by assertMnemonic when an array of mnemonic words does not contain one of the BIP-39 valid word counts. The only accepted lengths are [12, 15, 18, 21, 24] (the MNEMONIC_SIZES constant), because each maps to a fixed entropy+checksum bit layout. Any other count makes entropy recovery mathematically impossible.

Solutions

1. Verify the word count is one of 12, 15, 18, 21, or 24 before calling mnemonicToEntropy.
2. Split the phrase with phrase.trim().split(/\s+/) to avoid empty tokens from leading/trailing/multiple spaces.
3. If the phrase came from a user, prompt them to re-enter the complete, unmodified seed phrase.
4. Use getWords(phrase) from @fuel-ts/account mnemonic utils to normalize string-vs-array input before validation.

Example fix

// before
const words = phrase.split(' '); // may produce [''] or wrong count
const entropy = Mnemonic.mnemonicToEntropy(words);

// after
const words = phrase.trim().split(/\s+/);
if (![12, 15, 18, 21, 24].includes(words.length)) {
  throw new Error(`Expected 12/15/18/21/24 words, got ${words.length}`);
}
const entropy = Mnemonic.mnemonicToEntropy(words);

import { MNEMONIC_SIZES } from '@fuel-ts/account';
function normalizeWords(phrase: string | string[]): string[] {
  const words = Array.isArray(phrase) ? phrase : phrase.trim().split(/\s+/);
  if (!MNEMONIC_SIZES.includes(words.length)) {
    throw new Error(`Mnemonic must have ${MNEMONIC_SIZES.join('/')} words; got ${words.length}`);
  }
  return words;
}

function isValidMnemonicLength(words: string[]): boolean {
  return [12, 15, 18, 21, 24].includes(words.length);
}

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  const entropy = Mnemonic.mnemonicToEntropy(words);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.INVALID_MNEMONIC) {
    // prompt user for the full, correctly-sized phrase
  }
  throw e;
}

When it happens

Trigger: Calling Mnemonic.mnemonicToEntropy(words) or mnemonicToEntropy with an array whose length is not 12/15/18/21/24; splitting a phrase incorrectly (e.g. on commas or extra whitespace) producing stray empty entries; passing a partial or truncated phrase; mixing word counts from different sources.

Common situations: User edited/copy-pasted a seed phrase and dropped or duplicated a word; splitting on the wrong delimiter (e.g. splitting on newlines that leave empty strings); importing a 12-word phrase into a flow expecting 24 words; concatenating two phrases.

Related errors

• INVALID_CHECKSUM
• INVALID_ENTROPY
• INVALID_MNEMONIC
• INVALID_SEED
• INVALID_WORD_LIST

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

Appendix: source

Thrown at packages/account/src/mnemonic/mnemonic.ts:46

  }
}

function assertEntropy(entropy: BytesLike) {
  if (entropy.length % 4 !== 0 || entropy.length < 16 || entropy.length > 32) {
    throw new FuelError(
      ErrorCode.INVALID_ENTROPY,
      `Entropy should be between 16 and 32 bytes and a multiple of 4, but got ${entropy.length} bytes.`
    );
  }
}

function assertMnemonic(words: Array<string>) {
  if (!MNEMONIC_SIZES.includes(words.length)) {
    const errorMsg = `Invalid mnemonic size. Expected one of [${MNEMONIC_SIZES.join(
      ', '
    )}] words, but got ${words.length}.`;

    throw new FuelError(ErrorCode.INVALID_MNEMONIC, errorMsg);
  }
}

class Mnemonic {
  wordlist: Array<string>;

  /**
   *
   * @param wordlist - Provide a wordlist with the list of words used to generate the mnemonic phrase. The default value is the English list.
   * @returns Mnemonic instance
   */
  constructor(wordlist: Array<string> = english) {
    this.wordlist = wordlist;

    assertWordList(this.wordlist);
  }

  /**

View on GitHub (pinned to b3f37c91ac)