FuelLabs/fuels-ts · error · FuelError

INVALID_ADDRESS

INVALID_ADDRESS

Error message

Invalid address

What it means

Thrown by the addressify() utility (packages/address/src/utils.ts:75) when the input cannot be resolved to an Address. The function accepts an Address instance (duck-typed by the presence of a 'b256Address' property), an object with an '.address' property that is itself an Address, or an object with an '.id' property that is an Address. If none of these three shapes match, the SDK cannot extract an address and throws INVALID_ADDRESS. This helper is used pervasively across the SDK wherever a dynamic AddressLike or ContractIdLike input must be normalized.

Source

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

/**
 * Takes an indeterminate address type and returns an address
 *
 * @hidden
 */
export const addressify = (addressLike: AddressLike | ContractIdLike): Address => {
  if (isAddress(addressLike)) {
    return addressLike;
  }

  if ('address' in addressLike && isAddress(addressLike.address)) {
    return addressLike.address;
  }

  if ('id' in addressLike && isAddress(addressLike.id)) {
    return addressLike.id;
  }

  throw new FuelError(FuelError.CODES.INVALID_ADDRESS, 'Invalid address');
};

/**
 * @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)) {

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Wrap the raw value in an Address instance before passing it: new Address(value) or Address.fromDynamicInput(value).
2. If you hold a Contract object, pass the object itself — it exposes an 'id' property — rather than contract.id (a string).
3. If you hold an Account or Wallet, pass the object itself — it exposes an 'address' property.
4. Check the callee's parameter type: it expects AddressLike | ContractIdLike, not a bare string.

Example fix

// before
const params = [someRawHexString, amount];
contract.functions.mint(...params);

// after
const params = [new Address(someRawHexString), amount];
contract.functions.mint(...params);

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

function resolveAddress(input: unknown): Address {
  if (input instanceof Address) return input;
  if (typeof input === 'object' && input !== null) {
    if ('address' in input && isAddress(input.address as object)) return input.address;
    if ('id' in input && isAddress(input.id as object)) return input.id;
  }
  if (typeof input === 'string') return new Address(input);
  throw new Error('Cannot resolve input to Address');
}

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

function isAddressLike(value: unknown): value is Address {
  if (isAddress(value as object)) return true;
  if (typeof value !== 'object' || value === null) return false;
  if ('address' in value && isAddress((value as any).address)) return true;
  if ('id' in value && isAddress((value as any).id)) return true;
  return false;
}

try {
  const addr = addressify(input);
} catch (e) {
  if (e.code === 'invalid-address') {
    // input is not AddressLike or ContractIdLike; wrap or reject
  }
  throw e;
}

When it happens

Trigger: Calling addressify() — or any SDK function that internally calls it — with a raw string, a number, a plain object without b256Address/address/id keys, or an object whose nested .address or .id value lacks the b256Address property (i.e. is not a real Address instance).

Common situations: Passing a contractId string where an Address or AddressLike object is required; passing a primitive or mis-typed value through an untyped boundary (e.g. from JSON or user input); passing a Contract that has been serialized/deserialized losing its Address identity; confusing which field a wrapper object exposes.

Related errors

• INVALID_TRANSACTION_INPUT
• INVALID_B256_ADDRESS
• INVALID_EVM_ADDRESS
• INVALID_PUBLIC_KEY
• ABI_TYPES_AND_VALUES_MISMATCH

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