Errori delle transazioni Ethereum spiegati: cosa significa ogni messaggio e come risolverlo

1. Da dove vengono questi messaggi di errore?

Quasi tutti i wallet, le librerie e i provider RPC fanno passare il testo dell'errore prodotto da go-ethereum, il client Ethereum più diffuso, e i client delle reti Layer 2 riutilizzano le stesse stringhe. MetaMask le incapsula nella sua finestra di dialogo, ethers.js aggiunge un codice come NONCE_EXPIRED o REPLACEMENT_UNDERPRICED, e un provider RPC le restituisce come errore JSON-RPC con codice -32000. Sotto, il messaggio è lo stesso.

Il nodo esegue due serie diverse di controlli. La prima avviene quando riceve la transazione: il nonce è giusto, la fee è accettabile, il gas limit è sensato, il mittente può pagare. Una transazione che fallisce qui viene scartata e nulla viene registrato on-chain. La seconda avviene quando la transazione viene eseguita dentro un blocco: il codice del contratto arriva alla fine entro il gas limit senza fare revert. Una transazione che fallisce qui viene minata lo stesso, con stato Fail sull'explorer, e la fee è spesa.

Sapere a quale famiglia appartiene un errore ti dice due cose in una volta sola: se hai perso denaro, e se la soluzione sta dalla tua parte (la transazione) o dalla parte del contratto (gli input).

2. Riferimento rapido: tutti gli errori comuni

Le stringhe esatte, nell'ordine in cui è più probabile incontrarle. La formulazione è quella del codice sorgente di go-ethereum; i wallet a volte la accorciano.

3. Cosa significa "nonce too low"?

Ogni account numera le sue transazioni partendo da zero, e ogni numero può essere usato una volta sola. "Nonce too low" significa che la transazione che hai appena inviato porta un numero che la rete ha già confermato per quell'account. Il nodo confronta il nonce nella tua transazione con il prossimo nonce atteso per l'account e rifiuta qualsiasi valore inferiore.

Succede quando l'idea che il wallet ha del prossimo nonce è obsoleta: una transazione è stata inviata dallo stesso account da un altro wallet o dispositivo, un'accelerazione o un annullamento ha già preso quel numero, oppure una chain di sviluppo locale è stata riavviata e il contatore dell'account è tornato a zero mentre MetaMask ha continuato a contare. Su un hardware wallet compare anche quando una transazione viene firmata due volte.

La soluzione è lasciare che il wallet si risincronizzi. Prima cerca l'indirizzo sull'explorer: se quello che stavi cercando di fare è già passato con quel nonce, non reinviare. Se il wallet continua a proporre un numero obsoleto, l'opzione "Delete activity and nonce data" (elimina attività e dati del nonce) di MetaMask (Impostazioni, Strumenti per sviluppatori) azzera il contatore locale per la rete corrente. MetaMask precisa che è irreversibile, riguarda solo la rete corrente e non tocca il tuo saldo. Nel codice, leggi il prossimo nonce con eth_getTransactionCount usando il tag "pending" prima di firmare, invece di tenere un contatore tuo.

4. Cosa significa "nonce too high"?

Il divario opposto. Il nonce della transazione è sopra il prossimo valore atteso per l'account, quindi c'è un buco: un numero più basso non è ancora stato confermato. I nodi tengono una transazione del genere in coda invece di eseguirla, e alcuni la rifiutano subito con questo messaggio.

Causa tipica: un lotto di transazioni in cui una precedente è stata scartata, oppure un reset della chain locale nella direzione opposta (la chain è stata resettata ma il wallet no, quindi il wallet invia il nonce 40 a una chain che si aspetta il nonce 0). Colma il buco inviando il nonce mancante, oppure cancella i dati di attività del wallet come sopra.

5. Cosa significa "replacement transaction underpriced"?

Hai provato a sostituire una transazione in attesa (accelerarla, annullarla o semplicemente reinviarla con lo stesso nonce) e la nuova non paga abbastanza di più della vecchia. Il nodo scambia una transazione in attesa con un'altra con lo stesso nonce solo se la fee aumenta di una percentuale minima; in go-ethereum quell'aumento di prezzo è per impostazione predefinita del 10 per cento, e vale sia per la max fee sia per la priority fee.

Il nonce è corretto; il problema è il prezzo. Aumenta entrambi i campi della fee di almeno il 10 per cento rispetto alla transazione in attesa, non rispetto alla tariffa attuale della rete. Le indicazioni di MetaMask per la finestra collegata "transaction underpriced" sono una priority fee più alta di almeno il 10 per cento e una max fee più alta di almeno il 30 per cento. Per annullare invece, invia 0 ETH al tuo stesso indirizzo con lo stesso nonce e la fee aumentata, come descritto nella guida agli errori di MetaMask. In entrambi i casi la sostituta riceve un nuovo hash di transazione e la vecchia viene scartata.

6. Cosa significa "transaction underpriced"?

Senza la parola "replacement", questo è un semplice controllo di prezzo: la fee della tua transazione è sotto quanto il nodo è disposto a tenere nel suo pool. I nodi fissano un gas price minimo per tenere fuori lo spam, e in un periodo di traffico la stima "bassa" della fee di un wallet può finire sotto quella soglia. Il messaggio gemello "transaction gas price below minimum" significa la stessa cosa.

Alza la max fee e la priority fee e reinvia. Nulla è stato registrato on-chain, quindi non c'è nessuna transazione bloccata da liberare. Se lo vedi ripetutamente su una rete, il minimo di quella rete è più alto del valore predefinito del tuo wallet; le pagine per rete del gas tracker mostrano la tariffa corrente.

7. Cosa significa "insufficient funds for gas * price + value"?

Il saldo del mittente nella moneta nativa deve coprire l'importo inviato più la fee nel caso peggiore, cioè il gas limit moltiplicato per la max fee per gas. Quella regola è scritta in EIP-1559: il firmatario deve potersi permettere gas_limit per max_fee_per_gas, oltre al valore. Il nodo lo verifica contro il massimo, non contro quello che la transazione costerà davvero, quindi una transazione può fallire questo controllo anche se la fee finale ci sarebbe stata.

Tre cause coprono quasi tutti i casi. Hai token ma nessuna moneta nativa: USDC su Base ha bisogno di ETH per il gas, USDT su Polygon ha bisogno di POL, qualsiasi cosa su BNB Smart Chain ha bisogno di BNB. Stai inviando tutto il tuo saldo e non hai lasciato nulla per la fee: sottrai prima la fee massima. Oppure il gas limit è gonfiato da una chiamata a contratto, quindi il caso peggiore è molto sopra il costo reale.

Soluzione: ricarica la moneta nativa, invia un importo più piccolo, oppure abbassa la max fee o il gas limit se sono sovrastimati. Il messaggio collegato "insufficient funds for transfer" significa che il solo valore supera il saldo, ancora prima di considerare il gas.

8. Intrinsic gas too low, out of gas e gli errori di gas limit

Quattro messaggi riguardano il gas limit, e falliscono in momenti diversi. "Intrinsic gas too low" è un rifiuto prima dell'inclusione: ogni transazione ha un costo base fisso prima che venga eseguito qualsiasi codice, 21.000 gas per un trasferimento semplice più un addebito per ogni byte di dati, e il tuo gas limit è sotto quella soglia. La documentazione sul gas di ethereum.org fissa il trasferimento standard a 21.000 unità; un trasferimento di token o una chiamata a contratto ne richiede di più. Alza il limite, oppure lascia che lo stimi il wallet o la libreria.

"Out of gas" è la versione dopo l'inclusione. Il limite copriva il costo base, la transazione è stata minata, e poi il codice del contratto ha avuto bisogno di più di quanto il limite consentisse. L'EVM annulla ogni modifica di stato ma, come dice la stessa documentazione, tutto il gas fornito viene comunque consumato per il lavoro svolto. La fee è persa e la transazione compare come fallita sull'explorer. Reinvia con un limite più alto; i wallet di solito aggiungono un margine sopra la stima proprio per questo motivo.

"Exceeds block gas limit" significa che il limite che hai impostato è più grande di quanto un intero blocco possa contenere su quella rete. "Transaction gas limit too high" è più recente: da EIP-7825 in poi una singola transazione non può richiedere più di 16.777.216 gas (2 alla 24), e una transazione sopra il tetto viene rifiutata. Entrambi si risolvono abbassando il limite; una transazione legittima non ha mai bisogno di avvicinarsi a quei numeri.

9. Errori di max fee e priority fee

Da EIP-1559 una transazione porta due campi di fee: la max fee per gas, cioè il massimo che pagherai per unità, e la max priority fee per gas, la mancia per il validatore. Il protocollo impone due relazioni tra questi e la base fee del blocco, e ciascuna ha il suo errore.

"Max fee per gas less than block base fee": la tua max fee è sotto la base fee attuale, quindi la transazione non può essere inclusa con nessuna mancia. Colpisce le transazioni firmate in un periodo tranquillo e trasmesse dopo che la base fee è salita, e le transazioni costruite con una fee scritta a mano nel codice. Alza la max fee, oppure aspetta: la base fee si muove blocco dopo blocco e la transazione torna valida se scende sotto il tuo tetto.

"Max priority fee per gas higher than max fee per gas": la mancia supera il tetto totale, cosa che la specifica vieta perché la base fee viene coperta per prima e la mancia può venire solo da ciò che resta. Imposta la priority fee pari o inferiore alla max fee. Una transazione costruita correttamente ha una max fee pari a circa il doppio della base fee più la mancia, il che lascia spazio alla base fee per salire mentre aspetta.

10. Cosa significa "execution reverted"?

Il contratto che hai chiamato ha interrotto l'esecuzione di proposito. Le istruzioni require, revert e assert di Solidity finiscono tutte in questo messaggio, spesso seguito dalla stringa con il motivo scelta dal contratto: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" e così via. Quando il motivo è vuoto, vedi solo "execution reverted" o i dati grezzi dell'errore.

Nella maggior parte dei casi lo vedi prima di inviare, perché il wallet fa passare la chiamata per eth_estimateGas e la simulazione fa revert; MetaMask allora segnala che non riesce a stimare il gas. È la versione economica: non è stato inviato nulla. La versione costosa è una transazione che ha superato la simulazione, è stata minata e ha fatto revert on-chain perché nel frattempo lo stato è cambiato (il prezzo di uno swap si è spostato oltre il tuo slippage, qualcun altro ha comprato l'ultimo pezzo, una scadenza è passata). Compare come Fail sull'explorer e la fee si paga.

La soluzione non è mai un gas limit più alto. Leggi la stringa con il motivo, poi cambia gli input: approva prima il token, allarga lo slippage o riduci l'importo, controlla che il contratto non sia in pausa e verifica di essere sulla rete in cui il contratto vive. La pagina della transazione sull'explorer mostra il motivo del revert per i fallimenti minati; la guida a Etherscan mostra dove trovarlo.

11. Already known, invalid sender e oversized data

"Already known" non è un errore in alcun senso pratico. Il nodo ha già esattamente la transazione che hai inviato, di solito perché una libreria ha ritentato una trasmissione o due wallet hanno spinto gli stessi byte firmati. Aspetta che l'originale si confermi.

"Invalid sender" significa che il nodo non è riuscito a ricavare un firmatario valido dalla firma. Da EIP-155 il chain ID fa parte di ciò che viene firmato, quindi una transazione firmata per la chain 1 e inviata alla chain 137 produce un mittente senza senso e viene rifiutata. Confronta il chain ID nella configurazione di firma con quello che l'endpoint RPC riporta; la lista dei chain ID copre i numeri e il caso del mismatch.

"Oversized data" significa che la dimensione in byte della transazione supera quella che il nodo accetta nel suo pool, cosa che succede solo con deploy di contratti o calldata molto grandi. Dividi i dati, oppure fai il deploy tramite una factory.

12. Una transazione fallita costa gas?

Dipende da dove è fallita. Tutto ciò che sta nella prima famiglia di questa guida (nonce, underpriced, insufficient funds, intrinsic gas, tetto della fee, already known, invalid sender, oversized data) è un rifiuto: il nodo ha scartato la transazione e nessun blocco la contiene, quindi nessuna fee è stata addebitata e non c'è niente da trovare sull'explorer. Reinviare non costa nulla in più.

"Out of gas" e un "execution reverted" minato sono la seconda famiglia: la transazione è in un blocco con stato Fail, il validatore ha fatto il lavoro e la fee è pagata per intero. La documentazione di ethereum.org è esplicita: la fee si paga a prescindere dal fatto che una transazione riesca o fallisca. Gli ETH o i token che hai provato a spostare restano dov'erano; si perde solo la fee.

13. Come evitare questi errori nel codice

Quattro abitudini eliminano gran parte di questa lista da un servizio che invia transazioni: leggi il nonce in attesa dal nodo invece di tenere un contatore, prendi le stime delle fee dal nodo per la rete su cui ti trovi, stima il gas prima di firmare e aggiungi un margine, e controlla il saldo contro importo più fee nel caso peggiore prima di trasmettere. L'SDK ChainGate fa tutte e quattro le cose dentro transfer(), ed espone l'unico caso che devi gestire tu come errore tipizzato:

import { ChainGate, importWallet, NotEnoughFundsError } from 'chaingate';

const cg = new ChainGate({ apiKey: process.env.CHAINGATE_API_KEY });
const wallet = importWallet({ phrase: process.env.MNEMONIC });
const eth = cg.connect(cg.networks.ethereum, wallet);

try {
  // Nonce, gas limit and EIP-1559 fees are read from the node for you
  const tx = await eth.transfer(cg.networks.ethereum.amount('0.05'), '0x...');
  tx.setFee(tx.recommendedFees().normal);

  if (!tx.enoughFunds()) {
    // amount + worst-case fee exceeds the balance: nothing is broadcast
    console.log('short by', tx.missingFunds());
    return;
  }

  const sent = await tx.signAndBroadcast();
  console.log(sent.transactionId);
} catch (err) {
  if (err instanceof NotEnoughFundsError) {
    console.error('Not enough ETH for amount + fee');
  }
  throw err;
}

Il tutorial per inviare crypto in JavaScript mostra il flusso completo per Ethereum e per le chain UTXO, e la documentazione di transfer elenca i livelli di fee e il campo missingFunds che ti dice esattamente quanta moneta nativa manca.

14. Dove andare da qui

La maggior parte di questi errori riguarda le fee, quindi la pagina successiva da leggere è cosa sono le gas fee e come max fee, priority fee e base fee stanno insieme, seguita dal gas tracker per le tariffe di ogni rete in questo momento. Se una transazione è partita davvero e devi scoprire che fine ha fatto, la guida all'hash di transazione mostra come cercarla. E per una libreria TypeScript che gestisce nonce, fee e controlli del saldo su Ethereum, i Layer 2 EVM e Bitcoin, ChainGate è l'SDK dietro questo sito.

Domande frequenti