Ethereum-Transaktionsfehler erklärt: Was jede Meldung bedeutet und wie du sie behebst

1. Woher kommen diese Fehlermeldungen?

Fast jede Wallet, jede Bibliothek und jeder RPC-Anbieter reicht den Fehlertext durch, den go-ethereum erzeugt, der am weitesten verbreitete Ethereum-Client, und die Clients der Layer-2-Netzwerke verwenden dieselben Strings. MetaMask verpackt sie in einen eigenen Dialog, ethers.js ergänzt einen Code wie NONCE_EXPIRED oder REPLACEMENT_UNDERPRICED, und ein RPC-Anbieter gibt sie als JSON-RPC-Fehler mit dem Code -32000 zurück. Darunter ist die Meldung dieselbe.

Der Node führt zwei verschiedene Gruppen von Prüfungen durch. Die erste passiert, wenn er die Transaktion empfängt: Stimmt die Nonce, ist die Gebühr akzeptabel, ist das Gaslimit plausibel, kann der Absender zahlen. Eine Transaktion, die hier scheitert, wird verworfen, und nichts wird on-chain festgehalten. Die zweite passiert, wenn die Transaktion in einem Block ausgeführt wird: Läuft der Contract-Code innerhalb des Gaslimits durch, ohne zu reverten. Eine Transaktion, die hier scheitert, wird trotzdem gemint, mit dem Status Fail im Explorer, und die Gebühr ist ausgegeben.

Zu wissen, zu welcher Familie ein Fehler gehört, sagt dir zwei Dinge auf einmal: ob du Geld verloren hast und ob die Lösung auf deiner Seite liegt (die Transaktion) oder auf der Seite des Contracts (die Eingaben).

2. Schnellreferenz: jeder gängige Fehler

Die exakten Strings, in der Reihenfolge, in der du ihnen am ehesten begegnest. Der Wortlaut stammt aus dem Quellcode von go-ethereum; Wallets kürzen ihn manchmal.

3. Was bedeutet "nonce too low"?

Jedes Konto nummeriert seine Transaktionen von null an, und jede Nummer kann einmal verwendet werden. "Nonce too low" bedeutet, dass die Transaktion, die du gerade gesendet hast, eine Nummer trägt, die das Netzwerk für dieses Konto bereits bestätigt hat. Der Node vergleicht die Nonce in deiner Transaktion mit der nächsten erwarteten Nonce des Kontos und lehnt alles darunter ab.

Das passiert, wenn die Vorstellung der Wallet von der nächsten Nonce veraltet ist: Eine Transaktion wurde von demselben Konto aus einer anderen Wallet oder von einem anderen Gerät gesendet, ein Beschleunigen oder Abbrechen hat die Nummer schon verbraucht, oder eine lokale Entwicklungs-Chain wurde neu gestartet, sodass der Zähler des Kontos auf null zurückging, während MetaMask weitergezählt hat. Bei einer Hardware-Wallet taucht es auch auf, wenn eine Transaktion zweimal signiert wird.

Die Lösung ist, die Wallet neu synchronisieren zu lassen. Schlag die Adresse zuerst im Explorer nach: Wenn das, was du tun wolltest, unter dieser Nonce bereits durchgegangen ist, sende nicht erneut. Bietet die Wallet weiterhin eine veraltete Nummer an, löscht die Option "Delete activity and nonce data" (Aktivitäts- und Nonce-Daten löschen) von MetaMask unter Einstellungen, Entwicklertools den lokalen Zähler für das aktuelle Netzwerk. MetaMask weist darauf hin, dass das unumkehrbar ist, nur das aktuelle Netzwerk betrifft und dein Guthaben nicht anrührt. Im Code liest du die nächste Nonce vor dem Signieren mit eth_getTransactionCount und dem Tag "pending", statt einen eigenen Zähler zu führen.

4. Was bedeutet "nonce too high"?

Die Lücke in die andere Richtung. Die Nonce der Transaktion liegt über dem nächsten erwarteten Wert des Kontos, es gibt also ein Loch: Eine niedrigere Nummer wurde noch nicht bestätigt. Nodes halten eine solche Transaktion in einer Warteschlange, statt sie auszuführen, und manche lehnen sie mit dieser Meldung direkt ab.

Typische Ursache: eine Serie von Transaktionen, bei der eine frühere verworfen wurde, oder ein Reset der lokalen Chain in der anderen Richtung (die Chain wurde zurückgesetzt, die Wallet nicht, also sendet die Wallet Nonce 40 an eine Chain, die Nonce 0 erwartet). Schließe die Lücke, indem du die fehlende Nonce sendest, oder lösche die Aktivitätsdaten der Wallet wie oben beschrieben.

5. Was bedeutet "replacement transaction underpriced"?

Du hast versucht, eine ausstehende Transaktion zu ersetzen (beschleunigen, abbrechen oder einfach mit derselben Nonce erneut senden), und die neue zahlt nicht genug mehr als die alte. Der Node tauscht eine ausstehende Transaktion nur dann gegen eine andere mit derselben Nonce aus, wenn die Gebühr um einen Mindestprozentsatz steigt; in go-ethereum liegt dieser Preisaufschlag standardmäßig bei 10 Prozent, und er gilt sowohl für die Max Fee als auch für die Priority Fee.

Die Nonce stimmt; der Preis ist das Problem. Hebe beide Gebührenfelder um mindestens 10 Prozent über die ausstehende Transaktion an, nicht über den aktuellen Netzwerkpreis. MetaMasks eigene Empfehlung für den verwandten Dialog "transaction underpriced" lautet: eine mindestens 10 Prozent höhere Priority Fee und eine mindestens 30 Prozent höhere Max Fee. Um stattdessen abzubrechen, sende 0 ETH an deine eigene Adresse mit derselben Nonce und der erhöhten Gebühr, wie in MetaMasks Fehlerleitfaden beschrieben. So oder so bekommt der Ersatz einen neuen Transaktions-Hash, und die alte Transaktion wird verworfen.

6. Was bedeutet "transaction underpriced"?

Ohne das Wort "replacement" ist das eine reine Preisprüfung: Die Gebühr deiner Transaktion liegt unter dem, was der Node in seinem Pool halten will. Nodes setzen einen Mindest-Gaspreis, um Spam fernzuhalten, und in einer ausgelasteten Phase kann die "niedrige" Gebührenschätzung einer Wallet darunter landen. Die Schwestermeldung "transaction gas price below minimum" bedeutet dasselbe.

Erhöhe die Max Fee und die Priority Fee und sende erneut. Nichts wurde on-chain festgehalten, es gibt also keine hängende Transaktion, die du bereinigen müsstest. Siehst du die Meldung auf einem Netzwerk wiederholt, liegt das Minimum dieses Netzwerks über dem Standardwert deiner Wallet; die Netzwerkseiten des Gas-Trackers zeigen den üblichen Preis.

7. Was bedeutet "insufficient funds for gas * price + value"?

Das Guthaben des Absenders im nativen Coin muss den gesendeten Betrag plus die Gebühr im schlimmsten Fall decken, also das Gaslimit multipliziert mit der Max Fee pro Gas. Diese Regel steht in EIP-1559: Der Signierende muss sich gas_limit mal max_fee_per_gas zusätzlich zum Wert leisten können. Der Node prüft das gegen das Maximum, nicht gegen das, was die Transaktion tatsächlich kosten wird, eine Transaktion kann an dieser Prüfung also scheitern, obwohl die endgültige Gebühr gepasst hätte.

Drei Ursachen decken fast jeden Fall ab. Du hältst Token, aber keinen nativen Coin: USDC auf Base braucht ETH für Gas, USDT auf Polygon braucht POL, alles auf BNB Smart Chain braucht BNB. Du sendest dein gesamtes Guthaben und hast nichts für die Gebühr übrig gelassen: Zieh zuerst die maximale Gebühr ab. Oder das Gaslimit ist durch einen Contract-Aufruf aufgebläht, sodass der schlimmste Fall weit über den tatsächlichen Kosten liegt.

Lösung: Lade nativen Coin nach, sende einen kleineren Betrag oder senke die Max Fee oder das Gaslimit, wenn sie aufgepolstert sind. Das verwandte "insufficient funds for transfer" bedeutet, dass schon der Wert allein das Guthaben übersteigt, bevor Gas überhaupt berücksichtigt wird.

8. Intrinsic gas too low, out of gas und Gaslimit-Fehler

Vier Meldungen betreffen das Gaslimit, und sie scheitern zu unterschiedlichen Zeitpunkten. "Intrinsic gas too low" ist eine Ablehnung vor der Aufnahme: Jede Transaktion hat feste Grundkosten, bevor irgendein Code läuft, 21.000 Gas für eine einfache Überweisung plus eine Gebühr pro Byte an Daten, und dein Gaslimit liegt darunter. Die Gas-Dokumentation auf ethereum.org setzt die Standardüberweisung bei 21.000 Einheiten an; eine Token-Überweisung oder ein Contract-Aufruf braucht mehr. Erhöhe das Limit oder lass es von der Wallet oder Bibliothek schätzen.

"Out of gas" ist die Variante nach der Aufnahme. Das Limit hat die Grundkosten gedeckt, die Transaktion wurde gemint, und der Contract-Code brauchte dann mehr, als das Limit erlaubte. Die EVM macht jede Zustandsänderung rückgängig, aber wie dieselbe Dokumentation sagt, wird das gesamte bereitgestellte Gas für die geleistete Arbeit trotzdem verbraucht. Die Gebühr ist weg, und die Transaktion erscheint im Explorer als fehlgeschlagen. Sende mit einem höheren Limit erneut; Wallets schlagen aus genau diesem Grund meist eine Marge auf die Schätzung auf.

"Exceeds block gas limit" bedeutet, dass das gesetzte Limit größer ist, als ein ganzer Block auf diesem Netzwerk fassen darf. "Transaction gas limit too high" ist neuer: Seit EIP-7825 darf eine einzelne Transaktion nicht mehr als 16.777.216 Gas anfordern (2 hoch 24), und eine Transaktion über dieser Obergrenze wird abgelehnt. Beide behebst du, indem du das Limit senkst; eine legitime Transaktion braucht nie auch nur annähernd solche Zahlen.

9. Max-Fee- und Priority-Fee-Fehler

Seit EIP-1559 trägt eine Transaktion zwei Gebührenfelder: die Max Fee pro Gas, also das Meiste, was du pro Einheit zahlst, und die Max Priority Fee pro Gas, das Trinkgeld für den Validator. Das Protokoll erzwingt zwei Beziehungen zwischen ihnen und der Base Fee des Blocks, und jede hat ihren eigenen Fehler.

"Max fee per gas less than block base fee": Deine Max Fee liegt unter der aktuellen Base Fee, die Transaktion kann also bei keinem Trinkgeld aufgenommen werden. Das trifft Transaktionen, die in einer ruhigen Phase signiert und nach dem Anstieg der Base Fee gesendet wurden, und Transaktionen mit fest einprogrammierter Gebühr. Erhöhe die Max Fee oder warte: Die Base Fee bewegt sich Block für Block, und die Transaktion wird wieder gültig, wenn sie unter deine Obergrenze fällt.

"Max priority fee per gas higher than max fee per gas": Das Trinkgeld übersteigt die Gesamtobergrenze, was die Spezifikation verbietet, weil zuerst die Base Fee bedient wird und das Trinkgeld nur aus dem Rest kommen kann. Setze die Priority Fee auf oder unter die Max Fee. Eine korrekt gebaute Transaktion hat eine Max Fee von ungefähr dem Doppelten der Base Fee plus Trinkgeld, was Spielraum lässt, falls die Base Fee während des Wartens steigt.

10. Was bedeutet "execution reverted"?

Der aufgerufene Contract hat die Ausführung absichtlich abgebrochen. Die Anweisungen require, revert und assert in Solidity enden alle in dieser Meldung, oft gefolgt vom eigenen Reason-String des Contracts: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" und so weiter. Ist der Grund leer, siehst du nur "execution reverted" oder die rohen Fehlerdaten.

Meistens siehst du die Meldung vor dem Senden, weil die Wallet den Aufruf durch eth_estimateGas laufen lässt und die Simulation revertet; MetaMask meldet dann, dass es das Gas nicht schätzen kann. Das ist die günstige Variante: Nichts wurde gesendet. Die teure Variante ist eine Transaktion, die die Simulation bestanden hat, gemint wurde und on-chain revertet ist, weil sich der Zustand dazwischen geändert hat (ein Swap-Preis hat deine Slippage überschritten, jemand anderes hat das letzte Stück gekauft, eine Deadline ist abgelaufen). Sie erscheint im Explorer als Fail, und die Gebühr ist gezahlt.

Die Lösung ist nie ein höheres Gaslimit. Lies den Reason-String und ändere dann die Eingaben: Gib den Token zuerst frei, erweitere die Slippage oder senke den Betrag, prüfe, ob der Contract nicht pausiert ist, und stelle sicher, dass du auf dem Netzwerk bist, auf dem der Contract liegt. Die Transaktionsseite des Explorers zeigt den Revert-Grund für geminte Fehlschläge; der Etherscan-Leitfaden zeigt, wo du ihn findest.

11. Already known, invalid sender und oversized data

"Already known" ist in keinem praktischen Sinn ein Fehler. Der Node hält genau die Transaktion, die du gesendet hast, bereits vor, meist weil eine Bibliothek einen Broadcast wiederholt hat oder zwei Wallets dieselben signierten Bytes geschickt haben. Warte, bis das Original bestätigt ist.

"Invalid sender" bedeutet, dass der Node aus der Signatur keinen gültigen Signierenden wiederherstellen konnte. Seit EIP-155 ist die Chain-ID Teil dessen, was signiert wird, eine für Chain 1 signierte und an Chain 137 gesendete Transaktion ergibt also Datenmüll und wird abgelehnt. Prüfe die Chain-ID in der Signierkonfiguration gegen das, was der RPC-Endpunkt meldet; die Chain-ID-Liste behandelt die Nummern und den Fall der Nichtübereinstimmung.

"Oversized data" bedeutet, dass die Bytegröße der Transaktion über dem liegt, was der Node in seinen Pool aufnimmt, was nur bei sehr großen Contract-Deployments oder Calldata vorkommt. Teile die Daten auf oder deploye über eine Factory.

12. Kostet eine fehlgeschlagene Transaktion Gas?

Das hängt davon ab, wo sie gescheitert ist. Alles aus der ersten Familie dieses Leitfadens (Nonce, underpriced, insufficient funds, intrinsic gas, Gebührenobergrenze, already known, invalid sender, oversized data) ist eine Ablehnung: Der Node hat die Transaktion verworfen, kein Block enthält sie, es wurde also keine Gebühr berechnet, und im Explorer gibt es nichts zu finden. Erneutes Senden kostet nichts extra.

"Out of gas" und ein gemintes "execution reverted" sind die zweite Familie: Die Transaktion steht mit dem Status Fail in einem Block, der Validator hat die Arbeit geleistet, und die Gebühr wird vollständig gezahlt. Die Dokumentation auf ethereum.org sagt ausdrücklich, dass die Gebühr unabhängig davon gezahlt wird, ob eine Transaktion gelingt oder scheitert. ETH oder Token, die du bewegen wolltest, bleiben, wo sie waren; nur die Gebühr ist verloren.

13. Wie du diese Fehler im Code vermeidest

Vier Gewohnheiten nehmen einem Sendedienst den Großteil dieser Liste ab: die pending Nonce vom Node lesen, statt einen Zähler zu führen, Gebührenschätzungen vom Node für das Netzwerk holen, auf dem du bist, das Gas vor dem Signieren schätzen und eine Marge aufschlagen, und das Guthaben gegen Betrag plus Gebühr im schlimmsten Fall prüfen, bevor du sendest. Das ChainGate SDK erledigt alle vier innerhalb von transfer() und liefert den einen Fall, den du selbst behandeln musst, als typisierten Fehler:

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;
}

Das Tutorial zum Senden von Krypto in JavaScript zeigt den vollständigen Ablauf für Ethereum und die UTXO-Chains, und die Dokumentation zu transfer führt die Gebührenstufen und das Feld missingFunds auf, das dir genau sagt, wie viel nativer Coin fehlt.

14. Wie es weitergeht

Die meisten dieser Fehler drehen sich um Gebühren, als Nächstes lohnt sich also die Seite dazu, was Gas Fees sind und wie Max Fee, Priority Fee und Base Fee zusammenspielen, gefolgt vom Gas-Tracker mit den aktuellen Preisen auf jedem Netzwerk. Ist eine Transaktion tatsächlich rausgegangen und du musst herausfinden, was mit ihr passiert ist, zeigt der Leitfaden zum Transaktions-Hash, wie du sie nachschlägst. Und wer eine TypeScript-Bibliothek sucht, die Nonces, Gebühren und Guthabenprüfungen auf Ethereum, den EVM-Layer-2s und Bitcoin übernimmt: ChainGate ist das SDK hinter dieser Seite.

Häufig gestellte Fragen