FuelLabs/fuels-ts · error · FuelError

MAX_INPUTS_EXCEEDED

MAX_INPUTS_EXCEEDED

Error message

The transaction exceeds the maximum allowed number of inputs. Tx inputs: ${tx.inputs.length}, max inputs: ${maxInputs}

What it means

Thrown by Provider.validateTransaction when the number of inputs on a transaction request exceeds the chain's consensus parameter txParameters.maxInputs. The chain will reject such a transaction, so the SDK fails during validation. The threshold comes from getChain() consensus parameters and may differ per network.

Source

Thrown at packages/account/src/providers/provider.ts:1107

  #cacheInputs(inputs: TransactionRequestInput[], transactionId: string): void {
    if (!this.cache) {
      return;
    }

    this.cache.set(transactionId, inputs);
  }

  /**
   * @hidden
   */
  async validateTransaction(tx: TransactionRequest) {
    const {
      consensusParameters: {
        txParameters: { maxInputs, maxOutputs },
      },
    } = await this.getChain();
    if (bn(tx.inputs.length).gt(maxInputs)) {
      throw new FuelError(
        ErrorCode.MAX_INPUTS_EXCEEDED,
        `The transaction exceeds the maximum allowed number of inputs. Tx inputs: ${tx.inputs.length}, max inputs: ${maxInputs}`
      );
    }

    if (bn(tx.outputs.length).gt(maxOutputs)) {
      throw new FuelError(
        ErrorCode.MAX_OUTPUTS_EXCEEDED,
        `The transaction exceeds the maximum allowed number of outputs. Tx outputs: ${tx.outputs.length}, max outputs: ${maxOutputs}`
      );
    }
  }

  /**
   * Submits a transaction to the chain to be executed.
   *
   * If the transaction is missing any dependencies,
   * the transaction will be mutated and those dependencies will be added.

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Reduce the number of inputs: combine UTXOs first via a consolidation transaction before the main tx.
2. Use the account's resource-fetching with larger per-resource amounts to need fewer inputs.
3. Check (await provider.getChain()).consensusParameters.txParameters.maxInputs and split the tx if needed.
4. If merging many messages, do it across multiple transactions.

Example fix

// before — single tx with too many inputs
const resources = await account.getResourcesToSpend([...]);
const tx = new ScriptTransactionRequest({});
tx.addResources(resources); // may exceed maxInputs

// after — consolidate first, then spend
// 1) run a merge tx to coalesce small UTXOs into fewer larger ones
// 2) re-fetch resources (fewer inputs) and build the real tx
const { maxInputs } = (await provider.getChain()).consensusParameters.txParameters;
if (resources.length > maxInputs.toNumber()) {
  throw new Error(`Too many inputs (${resources.length} > ${maxInputs}); consolidate first.`);
}

async function assertInputsUnderLimit(provider, tx) {
  const { maxInputs } = (await provider.getChain()).consensusParameters.txParameters;
  if (tx.inputs.length > maxInputs.toNumber()) {
    throw new Error(`Too many inputs (${tx.inputs.length} > ${maxInputs}); consolidate first.`);
  }
}

function inputsFitLimit(inputCount: number, maxInputs: { toNumber(): number }): boolean {
  return inputCount <= maxInputs.toNumber();
}

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  await provider.validateTransaction(tx);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.MAX_INPUTS_EXCEEDED) {
    // run a consolidation tx first, then retry with fewer inputs
  }
  throw e;
}

When it happens

Trigger: Calling provider.validateTransaction(tx) (or a send path that invokes it) with a transactionRequest whose inputs array is longer than maxInputs; batching many UTXOs/messages into one tx; not consolidating resources before a large transfer.

Common situations: Account has many small UTXOs and a transfer gathers them all; merging message inputs across epochs; an airdrop/merge script that sweeps dozens of coins; maxInputs lowered by a consensus parameter change on the network.

Related errors

• MAX_OUTPUTS_EXCEEDED
• COINS_ASSET_ID_MISMATCH
• GAS_LIMIT_TOO_LOW
• MAX_FEE_TOO_LOW
• ASSET_BURN_DETECTED

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