Skip to main content

Resolve common errors

In this section, we try to help you fix some of the most common errors that can happen when setting up and working with ActyxOS. To quickly find answers to your problem, navigate to the specific section on your development platform in the table of contents to the right. In addition, we hope we can give a few tips and tricks along the way that make working with ActyxOS even better.

Installation errors#

If you receive the following error during installation, please close the Windows Event Viewer and press Retry:


Startup errors#

Blocked ports#

ActyxOS uses a few IP ports for node communication and internal services. In order for ActyxOS to run flawlessly, please make sure that the following ports are free:

  1. 4001: Used for inter-node communication

  2. 4243: Exposes a WebSocket endpoint for Actyx Pond (only on localhost)

  3. 4454: Exposes the Event Service (only on localhost)

  4. 4457: Exposes the Console Service (only on localhost)

  5. 8080: Exposes an IPFS Gateway (only on localhost)

On Windows, you can resolve this as follows:

Node to Actyx CLI connection error#

First, check that you entered the right IP in the ax command. If you still cannot connect, the output of ax nodes ls returns one of the two possible reasons (if you are using the ActyxOS Node Manager, you can find this info in the Status tab):

  • ActyxOS is not reachable: This means that ActyxOS is not running on your node. Please start ActyxOS described in this guide.

  • Host is not reachable: This means that your development machine cannot connect to your node. Please check that your development machine and your node are in the same network, and your firewall(s) allows them to connect via port 4457.

Node to node connection errors#

on Android#

Check the configured bootstrap node address#

ActyxOS on Android is currently not able to resolve DNS names inside MultiAddrs fields and only supports ip4 or ip6 MultiAddrs. For example, if you want to connect to the public ActyxOS Bootstrap Node, you have to set the value


instead of


We are currently working on a fix for this. Check out our blog or release notes section for information on our new releases.

on Docker#

Docker-specific configurations#

Your ActyxOS nodes running on Docker are not able connect to each other if

  • you are running ActyxOS without network=host; and
  • your ActyxOS Bootstrap Node is not running in the same local network as your ActyxOS nodes

This is inherent in Docker, as a container has no access to the IP address of its host unless it is running with network=host. Therefore, you have to manually configure the address that your nodes are announcing via the announceAddress property in the node settings:

announceAddress: # Manually configured addresses to announce
- /ip4/
# These must be multiaddresses without peer id,
# i.e. ip4/<YOUR_IP>/tcp/4001

Did not find what you were looking for?#

If you couldn't a solution to your problem, please don't hesitate us. You can either open a support ticket in our community forum, visit our Discord server and post your question there. Alternatively, you can always write us an e-mail. We'll do our best to get back to you with answers as fast as possible.