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.

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)

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_ENTROPY
• INVALID_SEED
• INVALID_MNEMONIC
• INVALID_CHECKSUM
• INVALID_WORD_LIST

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