Troubleshooting

Common build, peering, and runtime issues with their causes and fixes.

Fixing Common Issues

If something isn't working, you're probably hitting one of the issues below. This page covers the most frequent problems with building, running, and connecting AXL nodes, along with their fixes.

Build Problems

These issues come up when compiling the node binary or generating keys before you ever run anything.

ed25519 key generation fails on macOS

If openssl genpkey fails with "algorithm ed25519 not found," it's because macOS ships with LibreSSL, which doesn't support ed25519.

Install and use Homebrew's OpenSSL instead:

brew install openssl
/opt/homebrew/opt/openssl/bin/openssl genpkey -algorithm ed25519 -out private.pem

Go 1.26+ build tag errors

The gvisor.dev/gvisor dependency has build tag conflicts with Go 1.26.

Pin the toolchain for the build:

GOTOOLCHAIN=go1.25.5 go build -o node ./cmd/node/

Alternatively, install Go 1.25.x alongside your existing version:

go install golang.org/dl/go1.25.5@latest
go1.25.5 download
go1.25.5 build -o node ./cmd/node/

Running the Node

Once the binary is built, these are the issues you might hit when starting or connecting to your node.

Connection refused on port 9002

The node process isn't running, or you're pointing at the wrong port. Confirm the node is alive and responsive:

curl http://127.0.0.1:9002/topology

The default port is 9002. If you changed it in your config file, use your configured port instead.

"Address already in use"

A previous node instance or another process is still holding the port. Find and kill it:

lsof -ti :9002 | xargs kill

This is a common error that you will likely experience if you are testing out your application repeatedly with 2-4 terminals, especially if some are dedicated terminal instances vs. inside of Cursor or another IDE, etc.

Peering and Connectivity

Peering issues show up as missing messages or an empty topology. Most of the time, the fix is a config change or a short wait.

"No connected peers found"

You'll see this error if your node hasn't established any peer connections.

The most common causes are an empty Peers list in your config, unreachable or shut-down bootstrap nodes, or simply that peering hasn't had time to establish yet.

Give it a few seconds, then you can check your current connections with curl http://127.0.0.1:9002/topology and look at the peers array.

Messages not arriving between local test nodes

First, verify both nodes are running. Then confirm you're using the correct public key in the X-Destination-Peer-Id header.

When testing two nodes on the same machine, they need different tcp_port values to avoid conflicts. When communicating between separate machines, they should use the same tcp_port.

Messages not arriving between machines

Both nodes must be able to reach at least one common peer, whether that's a bootstrap node or a direct connection to each other.

Double-check that the bootstrap address is correct, the port is open, and firewalls or port forwarding aren't blocking traffic.

Python Client Issues

These apply when running the example scripts or any Python code that talks to a node's HTTP API.

Dependencie Issues

If you encounter this error (ModuleNotFoundError: No module named 'requests') it means that dependcies are either not installed or there was a failure during installation.

Run this command to install:

pip3 install -r examples/python-client/requirements.txt

urllib3 NotOpenSSLWarning

This is a harmless warning on macOS caused by a LibreSSL/OpenSSL mismatch in urllib3. Everything works correctly. You can safely ignore it.

Quick Reference

Symptom	Fix
Can't generate ed25519 key	Use /opt/homebrew/opt/openssl/bin/openssl
Build fails (Go 1.26)	GOTOOLCHAIN=go1.25.5 go build ...
Connection refused :9002	Start the node
Port conflict	lsof -ti :PORT | xargs kill
No peers	Check Peers in config, wait a few seconds
Python import errors	pip3 install -r requirements.txt