Filling required balances occupies a number of inputs more t

Error message

Filling required balances occupies a number of inputs more than can fit into the transaction

What it means

remaining_input_slots() computes how many free input slots the tx still has (max_inputs minus current inputs) and errors if the tx is already over max_inputs. It fires during assembly when the inputs added to satisfy required balances and fee have consumed more slots than the consensus parameter allows.

Source

Thrown at crates/fuel-core/src/schema/tx/assemble_tx.rs:408

        }

        self.estimate_script_if_possible().await?;

        self.remove_unused_variable_outputs();

        self = self.cover_fee().await?;

        self.adjust_witness_limit();

        Ok(self.tx)
    }

    fn remaining_input_slots(&self) -> anyhow::Result<u16> {
        let max_input = self.arguments.consensus_parameters.tx_params().max_inputs();
        let used_inputs = u16::try_from(self.tx.inputs().len()).unwrap_or(u16::MAX);

        if used_inputs > max_input {
            return Err(anyhow::anyhow!(
                "Filling required balances occupies a number \
                    of inputs more than can fit into the transaction"
            ));
        }

        Ok(max_input.saturating_sub(used_inputs))
    }

    async fn add_inputs_and_witnesses_and_changes(&mut self) -> anyhow::Result<()> {
        let required_balance = core::mem::take(&mut self.arguments.required_balances);

        for required_balance in required_balance {
            let remaining_input_slots = self.remaining_input_slots()?;

            let asset_id = required_balance.asset_id;
            let amount = required_balance.amount;
            let owner = required_balance.account.owner();

View on GitHub (pinned to b9d4d170da)

Solutions

Consolidate the wallet's UTXOs (sweep dust into one coin) before assembling
Reduce the number of requiredBalances entries or the tx's pre-existing inputs
If you operate the chain, raise max_inputs via consensus parameters

Example fix

// before
await client.assembleTx(txBytes, { requiredBalances: allAssets }); // wallet has 240 dust coins, tx has 20 inputs

// after
await consolidateUtxos(client, feeAccount); // one coin per asset
await client.assembleTx(txBytes, { requiredBalances: allAssets });

Defensive patterns

Strategy: validation

Validate before calling

const info = await client.request(gql`{ chain { consensusParameters { txParameters { maxInputs } } } }`);
const maxInputs = Number(info.chain.consensusParameters.txParameters.maxInputs);
const tx = Transaction.fromBytes(txBytes);
// each required balance may need >= 1 coin input
if (tx.inputs.length + requiredBalances.length > maxInputs) {
  throw new Error(`input budget exceeded: ${tx.inputs.length} + ${requiredBalances.length} > ${maxInputs}`);
}

Try / catch

catch (e) { if (/occupies a number of inputs more than can fit/.test(e.message)) { /* consolidate UTXOs / split tx, then retry */ } else throw e; }

Prevention

Track per-account UTXO counts and consolidate when they grow
Keep requiredBalances small per transaction
Remember the tx's own inputs count against the same budget

When it happens

Trigger: requiredBalances needing many coins (dusty wallets) so that, added to the tx's existing inputs, the total exceeds tx_params.max_inputs; each fee-covering iteration calls remaining_input_slots and re-checks the budget.

Common situations: Accounts with many small UTXOs; requiring many distinct assets/accounts in one transaction; custom chains with lowered max_inputs.

Related errors

AI-assisted analysis of FuelLabs/fuel-core@b9d4d170da (2026-08-16). Data as JSON: /api/errors/704fac1caa56204e. Report an issue: GitHub.