Skip to content
Algorand Developer Portal Algorand Developer Portal Algorand Developer Portal
This new developer portal is under construction. For complete documentation, please refer to the old developer portal.

Node Troubleshooting

If you are a developer, running a private network using AlgoKit provides more flexibility and is simpler.

Running a production node for MainNet benefits decentralization. However, like any unmanaged system (and any blockchain node/indexer), running a production node has many requirements to maintain high availability and reliability: appropriate redundancy (some upgrades create downtime on nodes), 24/7 monitoring, regular maintenance, and use of a staging environment for testing updates.

Consider using third-party API services or a third-party provider to help set up and maintain your node.

First steps

Ensure your $PATH and $ALGORAND_DATA environment variables are correctly set and your node is running. In particular:

goal node status

Should return something like:

Last committed block: 23119736
Time since last block: 0.1s
Sync Time: 2.7s
Last consensus protocol: https://github.com/algorandfoundation/specs/tree/d5ac876d7ede07367dbaa26e149aa42589aac1f7
Next consensus protocol: https://github.com/algorandfoundation/specs/tree/d5ac876d7ede07367dbaa26e149aa42589aac1f7
Round for next consensus protocol: 23119737
Next consensus protocol supported: true
Last Catchpoint:
Genesis ID: testnet-v1.0
Genesis hash: SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=

Read Install a Node to set these variables properly.

If you see:

  • Data directory not specified. Please use -d or set $ALGORAND_DATA in your environment. Exiting.: Your $ALGORAND_DATA is not properly set up.
  • command not found: goal: Your $PATH is not properly set up.
  • Cannot contact Algorand node: open ...: no such file or directory: The node is not started. Starting a node varies depending on the installation method.

Common Issues for algod

Most common issues: wrong version, wrong network, not caught up

The most common issues are that the node is on the wrong network, has the wrong algod version, or is not fully synced.

  • Check that the node is synced/caught up following Catchup and Status. See below if the node is not syncing.
  • Check that the node is on the right network: When running goal node status, Genesis ID must be mainnet-v1.0 for MainNet, testnet-v1.0 for TestNet, betanet-v1.0 for BetaNet. See Switch Networks to resolve this issue.
  • Check the version: The version reported by algod -v and goal version -v should be the latest stable release (for MainNet or TestNet) or the latest beta release (for BetaNet). See the official repo for all releases. Beta releases are marked.

My node is not syncing/catching up at all (Last Committed Block is 0)

The Last Committed Block from goal node status should increase when the node starts. If it stays at 0, the node isn’t syncing/catching up at all. This usually indicates a connectivity issue or DNS restriction from your ISP.

No connectivity

First, verify that your node has internet access. You can check using curl https://example.com in the command line.

DNS restrictions

By default, nodes get their relay list by reading DNS SRV records. To ensure these records aren’t tampered with, the node uses DNSSec.

The node first tries the system DNS. If that fails, it uses the fallback DNS from config.json (if provided). If this also fails, it tries hardcoded DNS from tools/network/dnssec/config.go.

Some ISPs, enterprise networks, or public networks only allow DNS queries to their DNS servers, which may not support DNSSec. In this case, set "DNSSecurityFlags": 0 in $ALGORAND_DATA/config.json.

:::caution Setting DNSSecurityFlags to 0 reduces node security and may allow attackers to connect your node to untrustworthy relays. While these relays cannot make your node accept invalid blocks or create invalid transactions, they may censor transactions or prevent syncing by withholding new blocks. Enable DNSSec in production whenever possible. :::

:::tip Remember to restart algod after any configuration changes. :::

To check your node’s DNS access, run these commands:

dig -t SRV _algobootstrap._tcp.mainnet.algorand.network +dnssec
dig -t SRV _algobootstrap._tcp.mainnet.algorand.network @8.8.8.8 +dnssec

At least one command should return a relay list without errors or warnings. The first command uses system DNS; the second uses Google DNS.

Other issues

Less common reasons for failing to catch up:

  • Check for the correct genesis.json file in $ALGORAND_DATA. See switch networks documentation.
  • For BetaNet, verify $ALGORAND_DATA/config.json has the correct DNSBootstrapID. See configuration for BetaNet.

My node is syncing/catching up very slowly (without fast-catchup)

As of November 2022, syncing without fast-catchup takes 2-4 weeks due to the blockchain’s size. Syncing slows as rounds increase since newer blocks typically contain more transactions.

:::tip Non-archival nodes can sync faster using fast-catchup. For archival nodes, nodely.io provides snapshots. This is not an endorsement - using these snapshots requires careful risk assessment since algod cannot verify their validity or that they don’t contain invalid data, allowing double spending. :::

If syncing appears to need much longer than 4 weeks:

  1. Verify your node meets the hardware requirements. MainNet requires at least 16GB of RAM and cannot run on HDD/slow-SATA-SSD/SD.
  2. Check for resource overuse:
    1. Monitor RAM and CPU usage with top or htop
    2. Check available disk space with df -h
  3. Verify your internet connection speed (need 100Mbps minimum) and latency (should be under 100ms).
  4. Some regions may have fewer relays, which can slow syncing. Latency above 100ms to the top 20 relays may cause issues. Check latency to the best relays using nodely.io scripts (from https://snap.algonode.cloud in the utils directory):
#!/bin/bash


# needs dig from dnsutils
N=$(dig +short srv _algobootstrap._tcp.mainnet.algorand.network @1.1.1.1 |wc -l)
echo "Querying $N nodes, be patient..."
echo "" > report.txt
for relay in $(dig +short srv _algobootstrap._tcp.mainnet.algorand.network @1.1.1.1|awk '{print $4 ":" $3}');
do
  echo -n .
  curl -s -o /dev/null --max-time 1 "http://$relay/v1/urtho/ledger/0"
  echo -ne '\bo'
  curl -s -o /dev/null --max-time 1 "http://$relay/v1/urtho/ledger/0" -w %{time_total} >> report.txt
  echo -ne '\b+'
  echo "s;$relay" >> report.txt
done


echo "Top 20 nodes"
sort -n report.txt | head -20
  1. Ensure $ALGORAND_DATA/config.json is absent or contains only necessary non-default parameters. Only modify parameters if you understand the implications - some changes can significantly slow syncing.

My node is not syncing/catching up with fast-catchup

See troubleshooting for fast-catchup.

Other issues

I get an overspend error when sending a transaction

If you receive an overspend error:

  1. Verify sufficient Algo in the account using a block explorer.
  2. Confirm your node is synced and on the right network.
  3. Remember to account for:
    1. The minimum balance requirement of 0.1 Algo for basic accounts (more for ASA or applications).
    2. The fee paid by the transaction sender.

None of the above works

If these solutions don’t help, check the third-party nodely.io FAQ.

If still unresolved, create a new Forum post with:

  • Your goal and what’s failing (include full command lines and outputs in triple backquotes)
  • OS version
  • Machine specs: CPU count, RAM size, disk type (NVMe SSD, SATA SSD, etc.)
  • Current usage: available memory, available disk space
  • algod -v output
  • goal version -v output
  • goal node status output
  • config.json content (from $ALGORAND_DATA)
  • Links to algod-out.log, algod-err.log, node.log (from $ALGORAND_DATA) uploaded to GitHub Gist or similar

:::tip Always enclose code/long outputs in triple backquotes or use the code button for better readability. :::