Iroha 3

Appearance

Troubleshooting Deployment Issues ​

This section offers troubleshooting tips for issues with Iroha 2 and Iroha 3 deployment. If the issue you are experiencing is not described here, contact us via Telegram.

Start with generated artifacts ​

For local and test deployments, prefer artifacts generated by Kagami instead of hand-written peer files:

bash
cargo run --bin kagami -- localnet --build-line iroha3 --peers 4 --out-dir ./localnet

The generated directory contains peer configs, genesis material, start scripts, and a README for the selected build line. Use --build-line iroha2 only when the deployment intentionally targets the Iroha 2 profile.

Peer does not start ​

Check these items first:

  • irohad --config <path> points at the peer's own TOML file.
  • public_key and private_key in the peer config belong to the same key pair.
  • genesis.public_key matches the key used to sign the genesis transaction.
  • validator peer identities use BLS-Normal keys, and trusted_peers_pop contains proof-of-possession entries for the local key and trusted peers.
  • ports for Torii and P2P are not already bound by another process.
  • the Kura store directory belongs to the same chain and was not copied from a different network profile.

Use config tracing when the daemon reads more than one TOML layer:

bash
cargo run --bin irohad -- --config ./config.toml --trace-config

Docker and Compose ​

Generate Compose from the current Kagami localnet output so the command-line arguments and config files match the checked-out code:

bash
cargo run --bin kagami -- localnet --build-line iroha3 --peers 4 --out-dir ./localnet
cargo run --bin kagami -- docker --peers 4 --config-dir ./localnet --image hyperledger/iroha:dev --out-file ./localnet/docker-compose.yml --force
docker compose -f ./localnet/docker-compose.yml up

If a compose deployment starts and then stalls, inspect the daemon logs for:

  • mismatched chain
  • one peer using a different genesis transaction or manifest
  • advertised P2P addresses that only work inside the container network
  • local volume reuse after regenerating genesis

When testing a fresh genesis, remove the old Kura volumes before restarting the stack. Keeping old block storage with a new genesis will make replay fail.

Kubernetes ​

For Kubernetes, treat each validator as stateful infrastructure:

  • give each peer a stable identity key and stable persistent volume
  • expose P2P addresses that other peers can resolve from inside the cluster
  • mount config and genesis files as immutable config for a rollout
  • roll out all genesis or topology changes deliberately, not as an automatic config-map refresh

If a pod restarts repeatedly, compare the rendered config in the pod with the expected peer.template.toml and check whether the peer is replaying old Kura data.

Sora profile ​

Iroha 3 deployments that use Nexus, SoraFS, or multi-lane flows should start the daemon with the Sora profile enabled:

bash
cargo run --bin irohad -- --config ./config.toml --sora

or:

bash
IROHA_SORA_PROFILE=true cargo run --bin irohad -- --config ./config.toml

Use the same profile consistently across validators in the same network.