FuelLabs/fuels-ts · error · FuelError

INVALID_EVM_ADDRESS

INVALID_EVM_ADDRESS

Error message

Invalid EVM address format.

What it means

Thrown by padFirst12BytesOfEvmAddress() (packages/address/src/utils.ts:119) when isEvmAddress(address) returns false. A valid EVM address is exactly 42 characters: 0x followed by 40 hex digits. The function pads the first 12 bytes of an EVM address so it can be used with Sway's EVM Address type. The same check is exercised indirectly through fromEvmAddressToB256(), which delegates to this function.

Source

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

    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
 * @returns Evm address padded to a b256 address
 *
 * @hidden
 */
export const padFirst12BytesOfEvmAddress = (address: string): B256AddressEvm => {
  if (!isEvmAddress(address)) {
    throw new FuelError(FuelError.CODES.INVALID_EVM_ADDRESS, 'Invalid EVM address format.');
  }

  return address.replace('0x', '0x000000000000000000000000') as B256AddressEvm;
};

/**
 * Converts an EVM address to a B256 address
 *
 * @param address - The EVM address to convert
 * @returns The B256 address
 *
 * @hidden
 */
export const fromEvmAddressToB256 = (address: string): B256Address =>
  padFirst12BytesOfEvmAddress(address);

/**
 * Converts a Public Key to a B256 address

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Validate with isEvmAddress() before calling padFirst12BytesOfEvmAddress() or fromEvmAddressToB256().
2. Ensure the input is a canonical Ethereum-style address: 0x + 40 hex characters, case-insensitive.
3. If you hold a B256 address, convert it to EVM format first using toB256AddressEvm(), not the reverse.

Example fix

// before
const padded = padFirst12BytesOfEvmAddress(b256String);

// after
import { isEvmAddress } from '@fuel-ts/address';
if (!isEvmAddress(evmString)) {
  throw new Error(`Expected EVM address, got: ${evmString}`);
}
const padded = padFirst12BytesOfEvmAddress(evmString);

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

if (!isEvmAddress(address)) {
  throw new Error(`Invalid EVM address: ${address}. Must be 0x + 40 hex characters.`);
}
const padded = padFirst12BytesOfEvmAddress(address);

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

function isEvmAddr(value: string): boolean {
  return value.length === 42 && /(0x)[0-9a-f]{40}$/i.test(value);
}
// Or use the exported isEvmAddress directly

try {
  const padded = padFirst12BytesOfEvmAddress(address);
} catch (e) {
  if (e instanceof FuelError && e.code === 'invalid-evm-address') {
    // address is not 0x + 40 hex; prompt user or reject
  }
  throw e;
}

When it happens

Trigger: Calling padFirst12BytesOfEvmAddress() or fromEvmAddressToB256() with a string that is not 42 characters matching 0x + 40 hex digits — e.g. a full B256 address (66 chars), a missing 0x prefix, uppercase beyond hex range, or a truncated value.

Common situations: Bridging addresses between EVM chains (Ethereum-style 20-byte addresses) and Fuel; passing a B256 address where a 20-byte EVM address is expected; address constants copied with a typo.

Related errors

• INVALID_B256_ADDRESS
• INVALID_EVM_ADDRESS
• INVALID_ADDRESS
• PARSE_FAILED
• INVALID_PUBLIC_KEY

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