FuelLabs/fuels-ts · error · FuelError

INVALID_B256_ADDRESS

INVALID_B256_ADDRESS

Error message

Invalid B256 Address: ${b256}.

What it means

Declared in toB256AddressEvm() (packages/address/src/utils.ts:94) when isB256(b256) returns false — the string is not 66 characters matching 0x + 64 hex digits. IMPORTANT: this throw lives inside a try block whose catch (line 100) re-wraps every error as PARSE_FAILED (error 162), so callers of toB256AddressEvm will never observe code INVALID_B256_ADDRESS from this path; they receive PARSE_FAILED with the message 'Cannot generate EVM Address B256 from: ...' instead. The code is documented here for completeness.

Source

Thrown at packages/address/src/utils.ts:94

};

/**
 * @hidden
 */
export const getRandomB256 = () => hexlify(randomBytes(32));

/**
 * Takes a B256 address and clears the first 12 bytes, this is required for an EVM Address
 *
 * @param b256 - the address to clear
 * @returns b256 with first 12 bytes cleared
 *
 * @hidden
 */
export const toB256AddressEvm = (b256: B256Address): B256AddressEvm => {
  try {
    if (!isB256(b256)) {
      throw new FuelError(FuelError.CODES.INVALID_B256_ADDRESS, `Invalid B256 Address: ${b256}.`);
    }

    const evmBytes = arrayify(b256).slice(12);
    const paddedBytes = new Uint8Array(12).fill(0);
    return hexlify(concat([paddedBytes, evmBytes])) as B256AddressEvm;
  } catch (error) {
    throw new FuelError(
      FuelError.CODES.PARSE_FAILED,
      `Cannot generate EVM Address B256 from: ${b256}.`
    );
  }
};

/**
 * Pads the first 12 bytes of an Evm address. This is useful for padding addresses returned from
 * the EVM to interact with the Sway EVM Address Type.
 *
 * @param address - Evm address to be padded

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Validate with isB256() before calling toB256AddressEvm() so you control the error path.
2. Ensure the input is a canonical B256 address: 0x followed by exactly 64 lowercase or uppercase hex characters.
3. If the value originates from user input or JSON, normalize it through Address.fromDynamicInput() or new Address() first.

Example fix

// before
toB256AddressEvm(maybeBadString);

// after
import { isB256 } from '@fuel-ts/address';
if (!isB256(maybeBadString)) throw new Error('Expected B256');
toB256AddressEvm(maybeBadString);

import { isB256 } from '@fuel-ts/address';

function safeToB256AddressEvm(b256: string) {
  if (!isB256(b256)) {
    throw new Error(`Expected B256 (0x + 64 hex), got: ${b256}`);
  }
  return toB256AddressEvm(b256);
}

import { isB256 } from '@fuel-ts/address';

function isValidB256(value: string): value is B256Address {
  return isB256(value);
}

try {
  const evm = toB256AddressEvm(b256);
} catch (e) {
  // Note: code will be PARSE_FAILED, not INVALID_B256_ADDRESS
  if (e.code === 'parse-failed') {
    // handle invalid B256 input
  }
  throw e;
}

When it happens

Trigger: Calling toB256AddressEvm with a string that fails isB256(): wrong length (not 66 chars), missing 0x prefix, contains non-hex characters, or is undefined/null. The thrown error is caught and re-thrown as PARSE_FAILED before it reaches the caller.

Common situations: Passing a checksummed/EVM-length address (42 chars) where a B256 (66 chars) is expected; passing a value that was silently coerced to a different string at runtime; typos or truncation in a hardcoded address constant.

Related errors

• PARSE_FAILED
• INVALID_EVM_ADDRESS
• INVALID_B256_ADDRESS
• INVALID_EVM_ADDRESS
• INVALID_ADDRESS

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