FuelLabs/fuels-ts · error · FuelError

FUNDS_TOO_LOW

FUNDS_TOO_LOW

Error message

Insufficient balance to deploy contract.

What it means

Thrown by ContractFactory.deployAsBlobTx() (packages/contract/src/contract-factory.ts:332) when the total estimated cost of all blob transactions plus the create (loader) transaction exceeds the account's current balance. The total cost is computed by summing calculateGasFee for each blob chunk's min gas and the create request's min gas, using the provider's estimated gas price and the chain's gasPriceFactor. This is a pre-flight check before any transaction is submitted.

Source

Thrown at packages/contract/src/contract-factory.ts:332

          gasPrice,
          gas: minGas,
          priceFactor,
          tip: transactionRequest.tip,
        }).add(1);

        totalCost = totalCost.add(minFee);
      }
      const createMinGas = createRequest.calculateMinGas(chainInfo);
      const createMinFee = calculateGasFee({
        gasPrice,
        gas: createMinGas,
        priceFactor,
        tip: createRequest.tip,
      }).add(1);
      totalCost = totalCost.add(createMinFee);
    }
    if (totalCost.gt(await account.getBalance())) {
      throw new FuelError(ErrorCode.FUNDS_TOO_LOW, 'Insufficient balance to deploy contract.');
    }

    // Transaction id is unset until we have funded the create tx, which is dependent on the blob txs
    let txIdResolver: (value: string | PromiseLike<string>) => void;
    const txIdPromise = new Promise<string>((resolve) => {
      txIdResolver = resolve;
    });

    const waitForResult = async () => {
      // Upload the blob if it hasn't been uploaded yet. Duplicate blob IDs will fail gracefully.
      const uploadedBlobs: string[] = [];
      // Deploy the chunks as blob txs
      for (const { blobId, transactionRequest } of chunks) {
        if (!uploadedBlobs.includes(blobId) && blobIdsToUpload.includes(blobId)) {
          const fundedBlobRequest = await this.assembleTx(transactionRequest, deployOptions);

          let result: TransactionResult<TransactionType.Blob>;

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Fund the deploying account with more base assets and retry.
2. Reduce the number of chunks by increasing chunkSizeMultiplier (closer to 1.0) so each blob carries more bytecode.
3. Wait for gas prices to decrease and retry, or set a lower tip in deployOptions.
4. Check account.getBalance() before deploying to fail fast with actionable information.

Example fix

// before
await factory.deployAsBlobTx();

// after
const balance = await account.getBalance();
if (balance.lte(0)) {
  throw new Error('Account has no base assets; fund it before deploying');
}
await factory.deployAsBlobTx();

const balance = await account.getBalance();
const { consensusParameters } = await account.provider.getChain();
const gasPrice = await account.provider.estimateGasPrice(10);

// Rough estimate: number of chunks * per-chunk gas cost
const estimatedCost = bn(estimatedGas).mul(gasPrice);
if (estimatedCost.gt(balance)) {
  throw new Error(`Insufficient balance (${balance}) for estimated deploy cost (${estimatedCost})`);
}
await factory.deployAsBlobTx();

try {
  await factory.deployAsBlobTx();
} catch (e) {
  if (e instanceof FuelError && e.code === 'funds-too-low') {
    // fund the account, then retry
    await fundAccount(account);
    await factory.deployAsBlobTx();
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling factory.deployAsBlobTx() (or factory.deploy() when bytecode exceeds the size limit) with an account whose base-asset balance is insufficient to cover the combined gas fees of all blob uploads and the final create transaction.

Common situations: Deploying a large contract with a freshly funded wallet that has not received enough base assets; gas price spikes on the network inflating the estimate; many blob chunks multiplying the per-chunk cost; deploying to a testnet with faucet limits.

Related errors

• CONTRACT_SIZE_EXCEEDS_LIMIT
• TRANSACTION_FAILED
• INVALID_CHUNK_SIZE_MULTIPLIER
• INSUFFICIENT_FUNDS
• MISSING_PROVIDER

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