Filling required balances occupies a number of inputs more…

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.

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.

Appendix: 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)