Troubleshooting NANO nodes and NANO development

Work in progress. On this page, I will collect some of the most common mistakes, along with possible fixes.

Common mistakes and pitfalls when developing with NANO

RPC Errors explained

'Gap source block'

When trying to make a "receive" type state block, the corresponding send-block hash was not found on this node. This can also happen due to the ambiguity of the "link" field: when you try to send funds but you made a mistake while calulating the balance, the node thinks that you want to receive from a nonexistent block.
If the block is supposed to exist, try restarting the node to get it back in sync.

'Gap previous'

The node does not find the block hash you set in the "previous" field. Make sure that you put the current "frontier" in there. Query account_info to get the current frontier.

'Error generating block'

"error": "error generating block" means that the account is not found in the local wallet. Probably a typo in the wallet ID. Use ./rai_node --wallet_list to see which wallet IDs your node knows.

'Account not found'

When using account_info: Most likely means that the ledger doesn't have an entry for that account since it never broadcasted a block, i.e. it means that the account has either no funds at all, or pending funds only. Interestingly enough, account_balance will not give this error but show 0 balances instead, if the account hasn't ever received anything at all.
If funds are stuck as "pending", the blocks may be below the receive_minimum threshold set in the config.json (keep in mind that this entry is in RAW format, so the default of 1000000000000000000000000 means one millionth NANO). Or it's stuck as pending due to a malfunction in the collection routine (you can try to use the receive command in that case).
If you're sure that you sent funds to the account but neither account_info nor pending shows a result, your node may be out of sync. Compare block_count with one of the block explorers. A high percentage of "unchecked" blocks also indicates synchronisation delays, whereas a smaller number of "unchecked" blocks is normal (it mostly contains blocks that don't have a predecessor).
In earlier versions, this error was also thrown when the wallet was locked, for example when using send.

'Unable to parse json'

"error": "Unable to parse JSON" probably means that the syntax is not correct, for example a missing argument. When using the process command, make sure that the actual block data is contained within a single line.

'Connection refused'

"curl: (7) Failed to connect to ::1 port 7072: Connection refused" means that the port is not accessible. For example, if the daemon is not running, or the remote host is not whitelisted in config.json

'Unreceivable'

1) Source block doesn't exist 2) Source has already been received 3) Trying to make an open bock when only state blocks are allowed since network upgrade

'Fork'

The node already knows another block with the same "previous". This violates the immutability of the chain continuity.

'command not found'

"error": "Unknown command" means that your "action" does not exist. Causes: 1) Typo 2) Deprecated 3) Introduced in a later node version

'bad destination account'

"error": "Bad destination account" means that the recipient is malformed (too short or too long) or has a typo in it (checksum incorrect, illegal letter, ...)

'Invalid amount number'

"error": "Invalid amount number" means that you didn't use a integer number between 0 and 2128. It needs to be in RAW (1 NANO is 1000000000000000000000000000000 RAW). This needs to be in integer form. Decimals and floats are not accepted. If you ever feel like you sent more than the recipient got, you may have forgotten the 10^30 multiplication factor from NANO to RAW. Keep in mind that by default, amounts smaller than 1 millionth NANO are ignored (you can adjust the threshold in config.json).

'bad source'

"error": "bad source" means that the sending account is malformed. Causes: Typos, wrong checksum, wrong prefix, wrong length, ...

'Bad wallet number'

"error": "Bad wallet number" means that your string is not a 64-character HEX string, i.e. it's too long or too short or contains non-hex-characters.

'Wallet not found'

"error": "Wallet not found" can have multiple causes. First of all, keep in mind that the node will never let you choose the wallet ID, it always is randomly assignes as it serves some kind of extra protection when it comes to wallet access - it's almost like an API token, except that it's also used to locally assign data, and you should do further considerations when it comes to API security.
Possible solutions are:
a) Restart your daemon after creating a wallet with CLI (not necessary for wallets created through RPC).
b) You probably mistook the Wallet ID for the seed. They serve different purposes.
c) You forgot the wallet ID? Use the CLI command `/opt/rai/bin/rai_node --wallet_list to see which wallets that particular node's database contains. By default, you can't retrieve Wallet IDs with an RPC command for security reasons.