FuelLabs/fuels-ts · error · FuelError

MAX_OUTPUTS_EXCEEDED

MAX_OUTPUTS_EXCEEDED

Error message

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

What it means

Thrown by Provider.validateTransaction when the number of outputs on a transaction request exceeds the chain's consensus parameter txParameters.maxOutputs. As with inputs, the chain would reject the tx, so validation fails fast. The limit is read from consensus parameters and may vary by network/upgrade.

Source

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

  /**
   * @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.
   *
   * @param transactionRequestLike - The transaction request object.
   * @param sendTransactionParams - The provider send transaction parameters (optional).
   * @returns A promise that resolves to the transaction response object.
   */
  async sendTransaction(
    transactionRequestLike: TransactionRequestLike,

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Split the transaction: batch recipients across several txs so each stays under maxOutputs.
2. Check (await provider.getChain()).consensusParameters.txParameters.maxOutputs and size outputs accordingly.
3. Prefer change outputs over explicit outputs where possible to reduce the count.
4. For distributions, stream transfers rather than one mega-tx.

Example fix

// before — too many recipient outputs in one tx
const tx = new ScriptTransactionRequest();
recipients.forEach(r => tx.addCoinOutput(r.address, r.amount, assetId));
await provider.validateTransaction(tx);

// after — chunk by maxOutputs
const { maxOutputs } = (await provider.getChain()).consensusParameters.txParameters;
const limit = maxOutputs.toNumber() - 1; // reserve a change output
for (const batch of chunk(recipients, limit)) {
  const tx = new ScriptTransactionRequest();
  batch.forEach(r => tx.addCoinOutput(r.address, r.amount, assetId));
  await provider.sendTransaction(tx); // one tx per batch
}

async function assertOutputsUnderLimit(provider, tx) {
  const { maxOutputs } = (await provider.getChain()).consensusParameters.txParameters;
  if (tx.outputs.length > maxOutputs.toNumber()) {
    throw new Error(`Too many outputs (${tx.outputs.length} > ${maxOutputs}); split the tx.`);
  }
}

function outputsFitLimit(outputCount: number, maxOutputs: { toNumber(): number }): boolean {
  return outputCount <= maxOutputs.toNumber();
}

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  await provider.validateTransaction(tx);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.MAX_OUTPUTS_EXCEEDED) {
    // split recipients across multiple txs and retry each
  }
  throw e;
}

When it happens

Trigger: Calling provider.validateTransaction(tx) with a transactionRequest.outputs longer than maxOutputs; building a batch transfer to many recipients in a single tx; adding a change output plus many explicit recipient outputs; adding variable outputs without limit.

Common situations: Airdrop/distribution tx with many recipients; adding multiple withdrawal outputs; mint/batch-mint script emitting many transfer outputs; maxOutputs lowered by a consensus parameter update.

Related errors

• MAX_INPUTS_EXCEEDED
• ASSET_BURN_DETECTED
• GAS_LIMIT_TOO_LOW
• MAX_FEE_TOO_LOW
• TRANSACTION_NOT_FOUND

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