FuelLabs/fuels-ts · error · FuelError

INVALID_WORD_LIST

INVALID_WORD_LIST

Error message

Expected word list length of 2048, but got ${wordlist.length}.

What it means

Thrown by assertWordList (called from the Mnemonic constructor and Mnemonic.entropyToMnemonic) when the supplied wordlist does not contain exactly 2048 entries. BIP-39 wordlists are fixed-size (2048 words = 11-bit indices); any other length breaks mnemonic-to-entropy/entropy-to-mnemonic indexing. The default English list is used if no wordlist is passed.

Source

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

import { english } from '../wordlists';

import type { MnemonicPhrase } from './utils';
import { entropyToMnemonicIndices, getWords, getPhrase, mnemonicWordsToEntropy } from './utils';

//
// Constants
//
// "Bitcoin seed"
const MasterSecret = toUtf8Bytes('Bitcoin seed');
// 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
const MainnetPRV = '0x0488ade4';
const TestnetPRV = '0x04358394';
export const MNEMONIC_SIZES = [12, 15, 18, 21, 24];

function assertWordList(wordlist: Array<string>) {
  if (wordlist.length !== 2048) {
    throw new FuelError(
      ErrorCode.INVALID_WORD_LIST,
      `Expected word list length of 2048, but got ${wordlist.length}.`
    );
  }
}

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(

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Omit the wordlist argument to use the default BIP-39 English list.
2. If supplying a custom list (e.g. another language), ensure it is the official 2048-word BIP-39 list for that language, unmodified.
3. Validate wordlist.length === 2048 before constructing the Mnemonic.

Example fix

// before
const m = new Mnemonic(myTruncatedWords);

// after
const m = new Mnemonic(); // uses default English BIP-39 list

function isValidWordlist(list: string[]): boolean {
  return Array.isArray(list) && list.length === 2048;
}

// Prefer the default; only override with a known-good 2048-word BIP-39 list
const m = new Mnemonic();
// or:
if (isValidWordlist(myList)) new Mnemonic(myList);

function isBip39Wordlist(list: unknown): list is string[] {
  return Array.isArray(list) && list.length === 2048;
}

try {
  const m = new Mnemonic(customList);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.INVALID_WORD_LIST) {
    // fall back to the default English wordlist
    const m = new Mnemonic();
  } else throw e;
}

When it happens

Trigger: Constructing new Mnemonic(myWords) with myWords.length !== 2048, or calling Mnemonic.entropyToMnemonic(entropy, customList) / mnemonicToEntropy with a short/long list. Not triggered when relying on the default English wordlist.

Common situations: Passing a truncated or extended wordlist, using a non-BIP-39 word collection, accidentally slicing the list, or loading a wordlist file that failed to parse into 2048 entries.

Related errors

• INVALID_ENTROPY
• INVALID_MNEMONIC
• INVALID_SEED
• INVALID_MNEMONIC
• INVALID_CHECKSUM

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