FuelLabs/fuels-ts · error · FuelError

INVALID_SEED

INVALID_SEED

Error message

Seed length should be between 16 and 64 bytes, but received ${seedArray.length} bytes.

What it means

Thrown by Mnemonic.masterKeysFromSeed when the BIP-39 seed passed to derive a BIP-32 master key is not between 16 and 64 bytes long. The seed is the output of PBKDF2 over the mnemonic phrase and must lie in this range for HMAC-SHA512 master-key derivation to be meaningful. Seeds outside this range indicate a malformed or truncated input.

Source

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

        right = mid - 1;
      } else {
        left = mid + 1;
      }
    }

    return false;
  }

  /**
   * @param seed - BIP39 seed
   * @param testnet - Inform if should use testnet or mainnet prefix, the default value is true (`mainnet`).
   * @returns 64-byte array contains privateKey and chainCode as described on BIP39
   */
  static masterKeysFromSeed(seed: string): Uint8Array {
    const seedArray = arrayify(seed);

    if (seedArray.length < 16 || seedArray.length > 64) {
      throw new FuelError(
        ErrorCode.INVALID_SEED,
        `Seed length should be between 16 and 64 bytes, but received ${seedArray.length} bytes.`
      );
    }

    return arrayify(computeHmac('sha512', MasterSecret, seedArray));
  }

  /**
   * Get the extendKey as defined on BIP-32 from the provided seed
   *
   * @param seed - BIP39 seed
   * @param testnet - Inform if should use testnet or mainnet prefix, default value is true (`mainnet`).
   * @returns BIP-32 extended private key
   */
  static seedToExtendedKey(seed: string, testnet: boolean = false): string {
    const masterKey = Mnemonic.masterKeysFromSeed(seed);
    const prefix = arrayify(testnet ? TestnetPRV : MainnetPRV);

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Generate the seed correctly via Mnemonic.mnemonicToSeed(phrase) before calling masterKeysFromSeed.
2. Confirm the seed buffer length is within 16–64 bytes after decoding (32 and 64 are typical PBKDF2-512 outputs).
3. If you already have a seed, validate seedArray.length with arrayify before the call.
4. Do not pass the raw mnemonic string or entropy bytes; pass the derived seed.

Example fix

// before
const master = Mnemonic.masterKeysFromSeed(phrase); // phrase is the mnemonic text

// after
const seed = Mnemonic.mnemonicToSeed(phrase); // correct 64-byte seed
const master = Mnemonic.masterKeysFromSeed(seed);

import { arrayify } from '@fuel-ts/utils';
function assertValidSeedLength(seed: string | Uint8Array) {
  const len = typeof seed === 'string' ? arrayify(seed).length : seed.length;
  if (len < 16 || len > 64) {
    throw new Error(`Seed must be 16..64 bytes; got ${len}`);
  }
}

function isValidSeedLength(seed: Uint8Array): boolean {
  return seed.length >= 16 && seed.length <= 64;
}

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  const master = Mnemonic.masterKeysFromSeed(seed);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.INVALID_SEED) {
    // re-derive seed via mnemonicToSeed and retry once
  }
  throw e;
}

When it happens

Trigger: Calling Mnemonic.masterKeysFromSeed(seed) where seed is a hex string or bytes whose decoded length is < 16 or > 64; passing the mnemonic phrase string itself instead of the PBKDF2-derived seed; passing an empty or undefined value that arrayifies to 0 bytes.

Common situations: Confusing the mnemonic phrase with the seed (the seed comes from mnemonicToSeed, not the raw phrase); passing a short hex value like '0x1234' (2 bytes); truncating a 64-byte seed during serialization; using a non-BIP-39 KDF output that is the wrong length.

Related errors

• INVALID_ENTROPY
• INVALID_MNEMONIC
• INVALID_MNEMONIC
• INVALID_CHECKSUM
• INVALID_WORD_LIST

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