Operate

Troubleshooting

Symptom, cause and fix. If something is not working, find the line that describes what you are seeing before you change any code.

Table

Symptom → cause → fix

Grouped by where the pain shows up, not by the layer the cause lives in.

Symptom	Likely cause	Fix
Writing
The second transaction of a burst is refused	Both read the same nextNonce because the first was not in the mempool yet.	Use a Remetente, which reserves the nonce locally instead of re-asking the node on every send.
aguardar_confirmacao returns TempoEsgotado	The deadline passed before inclusion. It is not a verdict: the transaction may land later.	Re-read /tx/:id. Only resend if it exists on no node — and never with a new nonce before that.
accepted: false with "transaction already known"	The same transaction is already in the mempool or already in a block.	Not an error. Stop resending and go straight to confirmation.
The destination received the amount twice	A resend under a new nonce after a timeout, creating a second valid transaction.	Treat a timeout as "I do not know", never as "it failed". Confirm by id before any resend.
The transaction is slow and raising the fee does not help	fee is a burn limit, not a bid. Selection order is (nonce, timestamp).	Check for a nonce gap ahead: one missing earlier transaction blocks every following one.
Reading
GET /address returns 404 for an account that exists	The account has never received anything — in state, it does not exist yet.	Treat 404 as zero balance and zero nonce. It is born on the first received transaction.
The balance you read does not match the explorer	Reading from a node behind the head, or at a height before finality.	Compare height from /status on both. For a definitive value, use saldo_provado.
Values appear a million times off	Mixing e7 (6 decimals) with wei (18), or parsing a big string as a JSON number.	Convert only at the boundary and use 128-bit integers or arbitrary decimals, never floats.
429 during read bursts	More than RATE_LIMIT_MAX requests within the window, from the same IP.	Honour Retry-After, group reads into a JSON-RPC batch, and paginate instead of sweeping.
EAVM and wallet
MetaMask shows a balance with too many decimals	The EAVM surface returns wei by EVM convention; the protocol's real unit has 6 decimals.	Not a display bug: divide by 10¹² to reach e7 when crossing to the native API.
The tool fails with -32601	The method is outside the implemented set — subscriptions and filters do not exist.	Check the missing list and switch to polling eth_getLogs or to the native API.
The wallet refuses to sign, saying wrong network	chainId configured as something other than 72020 (0x11954).	Re-add the network with the connect button, which uses the canonical parameters.
eth_getTransactionReceipt returns null	The transaction has not landed in a block yet, or it was born on the native API and is not mapped yet.	Poll for the receipt. For a native transaction, read /tx/:id, which is the source.
Your own node
The node never leaves height zero	No reachable peers: an empty --peers or a port closed by the firewall.	Check peers with eav7-cli status and open the API port for inbound traffic.
The node has stake but does not produce	Weight below the 27th place, listen mode, or stake under 1,000 EAV7.	Check account and score. Switching to candidate requires stake and a reachable address.
The node refuses blocks with a genesis error	A data directory from another network, or a build with different fork heights.	Recreate the directory with init --force and use the same binary as the rest of the mesh.
Port already in use on startup	Another Core in the same directory, or the port taken by another process.	Pick another port at init or stop the previous process before starting.

Diagnosis

The four questions, in order

Before changing a single line of code, answer these four. They isolate the problem between network, node, account and transaction.

bash

# 1. o nó está vivo e em que altura?
curl -s https://eavscan.com/status -H 'Accept: application/json' | jq '{height, finalizedHeight, validators}'

# 2. a transação existe em algum lugar?
curl -s https://eavscan.com/tx/0x8c1f… -H 'Accept: application/json'

# 3. o remetente está no nonce que você acha que está?
curl -s https://eavscan.com/address/E7A4B2…9F21 -H 'Accept: application/json' | jq '{nonce, nextNonce, balance, energy}'

# 4. a transação ficou pendurada no mempool?
curl -s https://eavscan.com/mempool -H 'Accept: application/json' | jq 'length'

Isolate before fixing

Most integration bugs are state bugs, not code bugs: a nonce read too early, a node behind the head, a unit converted twice. The four queries above show which of the three it is.

Where to go next