FuelLabs/fuels-ts · warning · FuelError

ERROR_BUILDING_BLOCK_EXPLORER_URL

ERROR_BUILDING_BLOCK_EXPLORER_URL

Error message

Only one of the following can be passed in to buildBlockExplorerUrl: ${customInputParams.map((param) => param.key).join(', ')}.

What it means

Thrown by `buildBlockExplorerUrl()` when more than one of the mutually-exclusive locator params (`address`, `txId`, `blockNumber`) is defined. The helper can only build a path for a single resource; passing multiple makes the target ambiguous, so it rejects before constructing an incorrect URL.

Source

Thrown at packages/account/src/providers/utils/block-explorer.ts:65

      value: txId,
    },
    {
      key: 'blockNumber',
      value: blockNumber,
    },
  ];

  const definedValues = customInputParams
    .filter((param) => !!param.value)
    .map(({ key, value }) => ({
      key,
      value,
    }));

  const hasAnyDefinedValues = definedValues.length > 0;

  if (definedValues.length > 1) {
    throw new FuelError(
      ErrorCode.ERROR_BUILDING_BLOCK_EXPLORER_URL,
      `Only one of the following can be passed in to buildBlockExplorerUrl: ${customInputParams
        .map((param) => param.key)
        .join(', ')}.`
    );
  }

  if (path && definedValues.length > 0) {
    const inputKeys = customInputParams.map(({ key }) => key).join(', ');
    throw new FuelError(
      ErrorCode.ERROR_BUILDING_BLOCK_EXPLORER_URL,
      `You cannot pass in a path to 'buildBlockExplorerUrl' along with any of the following: ${inputKeys}.`
    );
  }

  const pathGeneratedFromInputParams = hasAnyDefinedValues
    ? getPathFromInput(
        definedValues[0].key as BuildBlockExplorerUrlHelperParam,

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Pass exactly one of `address`, `txId`, or `blockNumber` to buildBlockExplorerUrl.
2. Add an upstream guard that selects the first defined locator and drops the rest.
3. Restructure the caller to issue separate buildBlockExplorerUrl calls per resource.

Example fix

// before
const url = buildBlockExplorerUrl({ address, txId }); // both set -> throws
// after
const url = buildBlockExplorerUrl(txId ? { txId } : { address });

function pickSingleLocator(o: { address?: string; txId?: string; blockNumber?: number }) {
  const defined = [o.address, o.txId, o.blockNumber].filter(Boolean);
  if (defined.length > 1) throw new Error('pass only one locator');
  return defined.length === 1 ? { address: o.address, txId: o.txId, blockNumber: o.blockNumber } : {};
}

null

null

When it happens

Trigger: Calling `buildBlockExplorerUrl({ address, txId })`, `buildBlockExplorerUrl({ txId, blockNumber })`, or any combination where two or more of the three are truthy. The `definedValues` array length exceeds 1.

Common situations: Generically forwarding a user-selected object containing several optional fields into buildBlockExplorerUrl; copy-paste from a config that sets both address and txId; UI that lets the user pick multiple entities and passes them all through.

Related errors

• INVALID_URL
• DUPLICATED_POLICY
• ABI_TYPES_AND_VALUES_MISMATCH
• ENCODE_ERROR
• ENCODE_ERROR

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