This is the multi-page printable view of this section. Click here to print.
Documentation
- 1: Simple Solo Setup
- 1.1: System Readiness
- 1.2: Quickstart
- 1.3: Managing Your Network
- 1.4: Upgrade Your Network
- 1.5: Upgrading an existing Solo installation
- 1.6: Cleanup
- 2: Advanced Solo Setup
- 2.1: Using Environment Variables
- 2.2: Network Deployments
- 2.2.1: One-shot Falcon Deployment
- 2.2.2: Falcon Values File Reference
- 2.2.3: Step-by-Step Manual Deployment
- 2.2.4: Custom Application Properties
- 2.2.5: Dynamically add, update, and remove Consensus Nodes
- 2.2.6: Consensus Node Environment Variables
- 2.3: Subprocess Environment Filtering
- 2.4: Attach JVM Debugger and Retrieve Logs
- 2.5: One-Shot Deploy with Custom Component Versions
- 2.6: Customizing Solo with Tasks
- 2.7: GitHub Actions CI Integration
- 2.8: Run Performance Tests Locally
- 2.9: CLI Reference
- 2.9.1: Solo CLI Reference
- 2.9.2: CLI Migration Reference
- 2.10: Solo Image Cache
- 2.11: Solo Helm Chart Cache
- 3: Using Solo
- 3.1: Accessing Solo Services
- 3.1.1: Using Solo with Mirror Node
- 3.2: Service Endpoints
- 3.3: Using Solo with Hiero SDKs
- 3.4: Using Solo with EVM Tools
- 3.5: Using Network Load Generator with Solo
- 3.6: Deploying a Local Consensus Node Build
- 4: Troubleshooting
- 4.1: Error Codes
- 4.1.1: Configuration
- 4.1.1.1: SOLO-1001
- 4.1.1.2: SOLO-1002
- 4.1.1.3: SOLO-1003
- 4.1.1.4: SOLO-1004
- 4.1.1.5: SOLO-1005
- 4.1.1.6: SOLO-1006
- 4.1.1.7: SOLO-1007
- 4.1.1.8: SOLO-1008
- 4.1.1.9: SOLO-1009
- 4.1.2: Deployment
- 4.1.2.1: SOLO-2001
- 4.1.2.2: SOLO-2002
- 4.1.2.3: SOLO-2003
- 4.1.2.4: SOLO-2004
- 4.1.2.5: SOLO-2005
- 4.1.2.6: SOLO-2006
- 4.1.2.7: SOLO-2007
- 4.1.2.8: SOLO-2008
- 4.1.2.9: SOLO-2009
- 4.1.2.10: SOLO-2010
- 4.1.2.11: SOLO-2011
- 4.1.2.12: SOLO-2012
- 4.1.2.13: SOLO-2013
- 4.1.2.14: SOLO-2014
- 4.1.2.15: SOLO-2015
- 4.1.2.16: SOLO-2016
- 4.1.2.17: SOLO-2017
- 4.1.2.18: SOLO-2018
- 4.1.2.19: SOLO-2019
- 4.1.2.20: SOLO-2020
- 4.1.2.21: SOLO-2021
- 4.1.2.22: SOLO-2022
- 4.1.2.23: SOLO-2023
- 4.1.2.24: SOLO-2024
- 4.1.2.25: SOLO-2025
- 4.1.2.26: SOLO-2026
- 4.1.2.27: SOLO-2027
- 4.1.2.28: SOLO-2029
- 4.1.2.29: SOLO-2030
- 4.1.2.30: SOLO-2031
- 4.1.2.31: SOLO-2033
- 4.1.2.32: SOLO-2034
- 4.1.2.33: SOLO-2035
- 4.1.3: Component
- 4.1.3.1: SOLO-3001
- 4.1.3.2: SOLO-3003
- 4.1.3.3: SOLO-3004
- 4.1.3.4: SOLO-3005
- 4.1.3.5: SOLO-3006
- 4.1.3.6: SOLO-3007
- 4.1.3.7: SOLO-3008
- 4.1.3.8: SOLO-3009
- 4.1.3.9: SOLO-3010
- 4.1.3.10: SOLO-3011
- 4.1.3.11: SOLO-3012
- 4.1.3.12: SOLO-3013
- 4.1.3.13: SOLO-3014
- 4.1.3.14: SOLO-3015
- 4.1.3.15: SOLO-3016
- 4.1.3.16: SOLO-3017
- 4.1.3.17: SOLO-3018
- 4.1.3.18: SOLO-3019
- 4.1.3.19: SOLO-3021
- 4.1.3.20: SOLO-3022
- 4.1.3.21: SOLO-3023
- 4.1.3.22: SOLO-3024
- 4.1.3.23: SOLO-3025
- 4.1.3.24: SOLO-3026
- 4.1.3.25: SOLO-3027
- 4.1.3.26: SOLO-3028
- 4.1.3.27: SOLO-3029
- 4.1.3.28: SOLO-3030
- 4.1.3.29: SOLO-3031
- 4.1.3.30: SOLO-3032
- 4.1.3.31: SOLO-3033
- 4.1.3.32: SOLO-3034
- 4.1.3.33: SOLO-3035
- 4.1.3.34: SOLO-3036
- 4.1.3.35: SOLO-3037
- 4.1.3.36: SOLO-3038
- 4.1.3.37: SOLO-3039
- 4.1.3.38: SOLO-3040
- 4.1.3.39: SOLO-3041
- 4.1.3.40: SOLO-3042
- 4.1.3.41: SOLO-3043
- 4.1.3.42: SOLO-3044
- 4.1.3.43: SOLO-3045
- 4.1.3.44: SOLO-3046
- 4.1.3.45: SOLO-3047
- 4.1.3.46: SOLO-3048
- 4.1.3.47: SOLO-3049
- 4.1.3.48: SOLO-3050
- 4.1.3.49: SOLO-3051
- 4.1.3.50: SOLO-3052
- 4.1.3.51: SOLO-3053
- 4.1.3.52: SOLO-3054
- 4.1.3.53: SOLO-3055
- 4.1.3.54: SOLO-3056
- 4.1.3.55: SOLO-3057
- 4.1.3.56: SOLO-3058
- 4.1.3.57: SOLO-3059
- 4.1.3.58: SOLO-3060
- 4.1.3.59: SOLO-3061
- 4.1.3.60: SOLO-3062
- 4.1.3.61: SOLO-3063
- 4.1.3.62: SOLO-3064
- 4.1.3.63: SOLO-3065
- 4.1.3.64: SOLO-3066
- 4.1.3.65: SOLO-3067
- 4.1.3.66: SOLO-3068
- 4.1.3.67: SOLO-3069
- 4.1.3.68: SOLO-3070
- 4.1.3.69: SOLO-3071
- 4.1.3.70: SOLO-3072
- 4.1.3.71: SOLO-3073
- 4.1.3.72: SOLO-3074
- 4.1.3.73: SOLO-3075
- 4.1.3.74: SOLO-3076
- 4.1.3.75: SOLO-3077
- 4.1.3.76: SOLO-3078
- 4.1.3.77: SOLO-3079
- 4.1.3.78: SOLO-3080
- 4.1.3.79: SOLO-3081
- 4.1.3.80: SOLO-3082
- 4.1.3.81: SOLO-3083
- 4.1.3.82: SOLO-3084
- 4.1.3.83: SOLO-3085
- 4.1.3.84: SOLO-3086
- 4.1.3.85: SOLO-3087
- 4.1.3.86: SOLO-3088
- 4.1.3.87: SOLO-3089
- 4.1.3.88: SOLO-3090
- 4.1.3.89: SOLO-3091
- 4.1.3.90: SOLO-3092
- 4.1.3.91: SOLO-3093
- 4.1.3.92: SOLO-3094
- 4.1.3.93: SOLO-3095
- 4.1.3.94: SOLO-3096
- 4.1.3.95: SOLO-3097
- 4.1.3.96: SOLO-3098
- 4.1.4: Validation
- 4.1.4.1: SOLO-4001
- 4.1.4.2: SOLO-4002
- 4.1.4.3: SOLO-4003
- 4.1.4.4: SOLO-4004
- 4.1.4.5: SOLO-4005
- 4.1.4.6: SOLO-4006
- 4.1.4.7: SOLO-4007
- 4.1.4.8: SOLO-4008
- 4.1.4.9: SOLO-4009
- 4.1.4.10: SOLO-4010
- 4.1.4.11: SOLO-4011
- 4.1.4.12: SOLO-4012
- 4.1.4.13: SOLO-4013
- 4.1.4.14: SOLO-4014
- 4.1.4.15: SOLO-4015
- 4.1.4.16: SOLO-4016
- 4.1.4.17: SOLO-4017
- 4.1.4.18: SOLO-4018
- 4.1.4.19: SOLO-4020
- 4.1.4.20: SOLO-4021
- 4.1.4.21: SOLO-4022
- 4.1.4.22: SOLO-4023
- 4.1.4.23: SOLO-4024
- 4.1.4.24: SOLO-4025
- 4.1.4.25: SOLO-4026
- 4.1.4.26: SOLO-4028
- 4.1.4.27: SOLO-4029
- 4.1.4.28: SOLO-4030
- 4.1.4.29: SOLO-4033
- 4.1.4.30: SOLO-4034
- 4.1.4.31: SOLO-4035
- 4.1.4.32: SOLO-4036
- 4.1.4.33: SOLO-4037
- 4.1.4.34: SOLO-4038
- 4.1.4.35: SOLO-4039
- 4.1.4.36: SOLO-4040
- 4.1.4.37: SOLO-4041
- 4.1.4.38: SOLO-4042
- 4.1.4.39: SOLO-4043
- 4.1.4.40: SOLO-4044
- 4.1.4.41: SOLO-4045
- 4.1.4.42: SOLO-4046
- 4.1.4.43: SOLO-4047
- 4.1.4.44: SOLO-4048
- 4.1.4.45: SOLO-4049
- 4.1.4.46: SOLO-4050
- 4.1.4.47: SOLO-4052
- 4.1.4.48: SOLO-4053
- 4.1.4.49: SOLO-4054
- 4.1.4.50: SOLO-4055
- 4.1.4.51: SOLO-4056
- 4.1.4.52: SOLO-4057
- 4.1.4.53: SOLO-4058
- 4.1.4.54: SOLO-4059
- 4.1.4.55: SOLO-4060
- 4.1.4.56: SOLO-4061
- 4.1.4.57: SOLO-4062
- 4.1.4.58: SOLO-4063
- 4.1.4.59: SOLO-4064
- 4.1.4.60: SOLO-4065
- 4.1.4.61: SOLO-4066
- 4.1.4.62: SOLO-4067
- 4.1.4.63: SOLO-4068
- 4.1.4.64: SOLO-4069
- 4.1.4.65: SOLO-4070
- 4.1.4.66: SOLO-4071
- 4.1.4.67: SOLO-4072
- 4.1.4.68: SOLO-4073
- 4.1.4.69: SOLO-4074
- 4.1.4.70: SOLO-4075
- 4.1.4.71: SOLO-4076
- 4.1.4.72: SOLO-4077
- 4.1.4.73: SOLO-4078
- 4.1.4.74: SOLO-4079
- 4.1.4.75: SOLO-4080
- 4.1.4.76: SOLO-4081
- 4.1.4.77: SOLO-4082
- 4.1.4.78: SOLO-4083
- 4.1.4.79: SOLO-4084
- 4.1.4.80: SOLO-4085
- 4.1.4.81: SOLO-4086
- 4.1.4.82: SOLO-4087
- 4.1.4.83: SOLO-4088
- 4.1.4.84: SOLO-4089
- 4.1.4.85: SOLO-4090
- 4.1.4.86: SOLO-4091
- 4.1.4.87: SOLO-4092
- 4.1.4.88: SOLO-4093
- 4.1.4.89: SOLO-4094
- 4.1.4.90: SOLO-4095
- 4.1.4.91: SOLO-4096
- 4.1.4.92: SOLO-4097
- 4.1.4.93: SOLO-5090
- 4.1.5: System
- 4.1.5.1: SOLO-2032
- 4.1.5.2: SOLO-5001
- 4.1.5.3: SOLO-5002
- 4.1.5.4: SOLO-5003
- 4.1.5.5: SOLO-5004
- 4.1.5.6: SOLO-5005
- 4.1.5.7: SOLO-5006
- 4.1.5.8: SOLO-5007
- 4.1.5.9: SOLO-5008
- 4.1.5.10: SOLO-5009
- 4.1.5.11: SOLO-5010
- 4.1.5.12: SOLO-5011
- 4.1.5.13: SOLO-5012
- 4.1.5.14: SOLO-5013
- 4.1.5.15: SOLO-5014
- 4.1.5.16: SOLO-5015
- 4.1.5.17: SOLO-5016
- 4.1.5.18: SOLO-5017
- 4.1.5.19: SOLO-5018
- 4.1.5.20: SOLO-5019
- 4.1.5.21: SOLO-5020
- 4.1.5.22: SOLO-5021
- 4.1.5.23: SOLO-5022
- 4.1.5.24: SOLO-5023
- 4.1.5.25: SOLO-5024
- 4.1.5.26: SOLO-5025
- 4.1.5.27: SOLO-5026
- 4.1.5.28: SOLO-5027
- 4.1.5.29: SOLO-5028
- 4.1.5.30: SOLO-5029
- 4.1.5.31: SOLO-5030
- 4.1.5.32: SOLO-5031
- 4.1.5.33: SOLO-5032
- 4.1.5.34: SOLO-5033
- 4.1.5.35: SOLO-5034
- 4.1.5.36: SOLO-5035
- 4.1.5.37: SOLO-5036
- 4.1.5.38: SOLO-5037
- 4.1.5.39: SOLO-5038
- 4.1.5.40: SOLO-5039
- 4.1.5.41: SOLO-5040
- 4.1.5.42: SOLO-5041
- 4.1.5.43: SOLO-5042
- 4.1.5.44: SOLO-5043
- 4.1.5.45: SOLO-5044
- 4.1.5.46: SOLO-5045
- 4.1.5.47: SOLO-5046
- 4.1.5.48: SOLO-5047
- 4.1.5.49: SOLO-5048
- 4.1.5.50: SOLO-5049
- 4.1.5.51: SOLO-5050
- 4.1.5.52: SOLO-5051
- 4.1.5.53: SOLO-5052
- 4.1.5.54: SOLO-5053
- 4.1.5.55: SOLO-5054
- 4.1.5.56: SOLO-5055
- 4.1.5.57: SOLO-5056
- 4.1.5.58: SOLO-5057
- 4.1.5.59: SOLO-5058
- 4.1.5.60: SOLO-5059
- 4.1.5.61: SOLO-5060
- 4.1.5.62: SOLO-5061
- 4.1.5.63: SOLO-5062
- 4.1.5.64: SOLO-5063
- 4.1.5.65: SOLO-5064
- 4.1.5.66: SOLO-5065
- 4.1.5.67: SOLO-5066
- 4.1.5.68: SOLO-5067
- 4.1.5.69: SOLO-5068
- 4.1.5.70: SOLO-5069
- 4.1.5.71: SOLO-5070
- 4.1.5.72: SOLO-5071
- 4.1.5.73: SOLO-5072
- 4.1.5.74: SOLO-5073
- 4.1.5.75: SOLO-5074
- 4.1.5.76: SOLO-5075
- 4.1.5.77: SOLO-5076
- 4.1.5.78: SOLO-5077
- 4.1.5.79: SOLO-5078
- 4.1.5.80: SOLO-5079
- 4.1.5.81: SOLO-5080
- 4.1.5.82: SOLO-5081
- 4.1.5.83: SOLO-5082
- 4.1.5.84: SOLO-5083
- 4.1.5.85: SOLO-5084
- 4.1.5.86: SOLO-5085
- 4.1.5.87: SOLO-5086
- 4.1.5.88: SOLO-5087
- 4.1.5.89: SOLO-5088
- 4.1.5.90: SOLO-5089
- 4.1.5.91: SOLO-5091
- 4.1.5.92: SOLO-5092
- 4.1.5.93: SOLO-5093
- 4.1.5.94: SOLO-5094
- 4.1.5.95: SOLO-5095
- 4.1.5.96: SOLO-9001
- 4.1.6: Internal
New to Solo? Start with the Quickstart → to deploy your first local network in one command.
Using Solo below v0.91.0? MinIO image pulls fail on those versions. Upgrade Solo, or see the workarounds in Troubleshooting.
Browse the docs
Get started with Solo quickly. This section guides you through prerequisites, one-command deployment, network management, and cleanup. Perfect for developers and testers getting their first Hiero network running locally.
Deep-dive into advanced deployment methods, network customization, and operational management. This section covers YAML-driven deployments, manual component orchestration, dynamic node management, and CI/CD integration. Ideal for DevOps engineers and system administrators requiring full control.
Explore practical applications and integrations for Solo. This section covers using Solo networks with the JavaScript SDK, integrating with external tools, building applications on Hiero consensus nodes, and deploying locally built consensus node binaries for development and testing.
Solutions to common issues when using Solo, plus guidance on getting help. This document covers installation problems, pod readiness issues, resource constraints, and how to find additional support.
1 - Simple Solo Setup
Verify hardware and software requirements before deploying a local Hiero test network with Solo. Check system prerequisites, install Docker/Podman, configure platform-specific settings, and ensure your machine is ready.
Deploy a local Hiero test network with a single command using the Solo CLI. This guide covers installation, one-shot deployment, network verification, and accessing local service endpoints.
Learn how to start, stop, and restart consensus nodes, reset the ledger to genesis, capture logs and diagnostics, and troubleshoot a running Solo network. Master day-to-day network operations and troubleshooting.
Learn how to upgrade an existing Solo network deployment to a newer Hiero version using the Solo CLI and verify compatibility before you begin.
Upgrade an existing Solo installation to the latest release - whether you installed via Homebrew or npm - and perform a clean reinstall when an upgrade leaves a broken or conflicting state.
Learn how to properly destroy a Solo network deployment, manage resource usage, and perform a full reset when the standard destroy command fails along with how to clean up resources safely and completely.
1.1 - System Readiness
Overview
Before you deploy a local Hiero test network with solo one-shot single deploy, your machine must meet specific hardware, operating system, and tooling requirements.
This page covers the minimum and recommended memory, CPU, and storage; supported platforms (macOS, Linux, and Windows — natively with PowerShell, or via WSL2); and the required versions of Docker/Podman, Node.js, and Kubernetes tooling.
By the end of this page, your container runtime will be installed and your platform environment configured. Then proceed to Quickstart to install Solo and deploy.
Hardware Requirements
Solo’s resource requirements depend on your deployment size:
| Configuration | Minimum RAM | Recommended RAM | Minimum CPU | Minimum Storage |
|---|---|---|---|---|
| Single-node | 12 GB | 16 GB | 4 cores | 20 GB free |
| Multi-node (3+ nodes) | 16 GB | 24 GB | 8 cores | 20 GB free |
Note: If you are using Docker Desktop, ensure the resource limits under Settings → Resources are set to at least these values - Docker caps usage independently of your machine’s total available memory.
Software Requirements
Solo sets up most of the tools it needs for you. The table below shows what each install method provides, what Solo provisions automatically, and what you must install yourself.
| Tool | Required version | How it is installed |
|---|---|---|
| Solo | latest | npm install -g @hiero-ledger/solo@latest (recommended); brew install hiero-ledger/tools/solo (deprecated - Homebrew support ends August 31, 2026) |
| Node.js | >= 22.0.0 (lts/jod) | You install it (required for npm); Homebrew installs it automatically (deprecated) |
| Container runtime (Docker / Podman) | See Docker below | You install it — Docker Desktop (macOS/Windows) or Docker Engine (Linux). Solo auto-installs Podman on Linux/macOS/WSL2 if Docker Engine is not found. Not supported on native Windows. |
| kubectl | >= v1.32.2 | Solo provisions it at deploy time - reuses a compatible copy already on your system, or downloads one into ~/.solo/bin |
| Helm | v3.14.2 | Solo provisions it at deploy time |
| Kind | >= v0.29.0 | Solo provisions it at deploy time |
| Kubernetes | >= v1.32.2 | Installed automatically by Kind |
| k9s (optional) | >= v0.27.4 | You install it |
Note: Solo’s provisioned copies of kubectl, Kind, and Helm live in
~/.solo/bin, which is not necessarily on yourPATH. If you want to runkubectl,kind, orhelmcommands yourself (some guides do), install kubectl, Kind, and Helm on yourPATHseparately.
Windows (WSL2) prerequisite
Kind (which Solo provisions automatically) requires WSL2 to be enabled on Windows, but you do not need a WSL2 Linux distro installed — only the WSL2 feature itself. Enable it with:
wsl --install --no-distribution
WSL2 requires hardware virtualization and the Virtual Machine Platform Windows
feature. If virtualization is unavailable (for example, wsl --install reports
HCS_E_HYPERV_NOT_INSTALLED), use the native Windows (PowerShell) path
instead, which does not require WSL2.
Docker
Solo requires Docker Desktop (macOS, Windows) or Docker Engine / Podman (Linux) with sufficient resources:
- Memory: at least 12 GB available for containers.
- CPU: at least 6 cores available for containers.
Configure Resources by Platform
macOS and Windows (Docker Desktop)
To allocate the required resources in Docker Desktop:
Open Docker Desktop.
Go to Settings > Resources > Memory and set it to at least 12 GB.
Go to Settings > Resources > CPU and set it to at least 6 cores.
Click Apply & Restart.

Note: If Docker Desktop does not have enough memory or CPU allocated, the one-shot deployment will fail or produce unhealthy pods.
Linux
Docker Engine on Linux uses system memory directly and does not have a resource allocation interface like Docker Desktop.
Resource Check:
- Ensure your machine has at least 12 GB of free RAM available before running
solo one-shot single deploy. - Check available memory with:
free -h - If you have insufficient RAM, the deployment may fail or pods may become unhealthy.
Podman on Linux: If using Podman instead of Docker Engine, ensure your system has at least 12 GB of free RAM available.
Platform Setup
Solo supports macOS, Linux, and Windows (natively with PowerShell, or via WSL2). Select your platform below to install the required container runtime and configure your environment, before proceeding to Quickstart:
⚠️ Homebrew support is being deprecated. Solo will stop publishing updates to Homebrew after August 31, 2026. New users should install via npm. Existing Homebrew users should migrate before August 31.
Install Node.js (>= 22.0.0):
Download from nodejs.org, or install via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.nvm/nvm.sh nvm install --ltsInstall Docker Desktop:
- Download from: https://www.docker.com/products/docker-desktop
- Start Docker Desktop and configure resources:
- Settings → Resources → Memory: set to at least 12 GB
- Settings → Resources → CPU: set to at least 6 cores
- Click Apply & Restart
macOS prerequisite: Docker Desktop must be open before running
solo one-shot single deploy. The Docker daemon is not started automatically on macOS, so confirm Docker Desktop is running from your menu bar before you begin.Install Solo:
npm install -g @hiero-ledger/solo@latestVerify the installation:
solo --version
Install Node.js (>= 22.0.0):
Using nvm (recommended):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.nvm/nvm.sh nvm install --ltsOr download from nodejs.org.
Install Docker Engine (Ubuntu/Debian):
sudo apt-get update sudo apt-get install -y docker.io sudo systemctl enable docker sudo systemctl start docker sudo usermod -aG docker ${USER}Log out and back in for the group changes to take effect.
Fedora/RHEL: Replace the
apt-getcommands above with your distro’s package manager. For example, on Fedora:sudo dnf install -y docker-ce docker-ce-cli containerd.io(after adding Docker’s dnf repo — see Docker’s Fedora guide). Then runsudo systemctl enable --now dockerandsudo usermod -aG docker ${USER}.Install Solo:
npm install -g @hiero-ledger/solo@latestVerify the installation:
solo --version
Run Solo natively from Windows PowerShell. Run every command below in a PowerShell terminal.
Install Docker Desktop for Windows:
- Download from: https://www.docker.com/products/docker-desktop.
- Start Docker Desktop and configure resources:
- Settings → Resources → Memory: set to at least 12 GB
- Settings → Resources → CPU: set to at least 6 cores
- Click Apply & Restart
Windows prerequisite: Docker Desktop must be running before you run
solo one-shot single deploy.Install Node.js (>= 22.0.0):
winget install OpenJS.NodeJS.LTSOr download the installer from nodejs.org.
Note: Open a new PowerShell window after installing tools so updated PATH entries take effect.
Your environment is ready. Proceed to Quickstart to install Solo and deploy.
Note: Make sure your machine meets the Windows (WSL2) prerequisite first. If WSL and a Linux distribution are already installed, skip step 1 (and you may use a distribution other than Ubuntu).
Run the following command in Windows PowerShell (as Administrator), then reboot and open the Ubuntu terminal. All subsequent commands must be run inside the Ubuntu (WSL2) terminal.
wsl --install UbuntuInstall Node.js (>= 22.0.0) inside the Ubuntu terminal:
Using nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.nvm/nvm.sh nvm install --ltsInstall Docker Desktop for Windows:
- Download from: https://www.docker.com/products/docker-desktop
- Enable WSL2 integration: Settings → Resources → WSL Integration
- Configure resources:
- Settings → Resources → Memory: set to at least 12 GB
- Settings → Resources → CPU: set to at least 6 cores
- Click Apply & Restart
Install Solo:
npm install -g @hiero-ledger/solo@latestVerify the installation:
solo --version
Optional Tools
The following tools are not required but are recommended for monitoring and managing your local network:
k9s (
>= v0.27.4): A terminal-based UI for managing Kubernetes clusters. Install it with:brew install k9sRun
k9sto launch the cluster viewer.
Version Compatibility Reference
| Solo Version | Node.js | Consensus Node | Kubernetes | Docker Resources | Release Date | End of Support |
|---|---|---|---|---|---|---|
| 0.98.0 (LTS) | >= 22.0.0 (lts/jod) | v0.78.1 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-17 | 2027-02-17 |
| 0.97.0 | >= 22.0.0 (lts/jod) | v0.78.1 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-10 | 2026-12-10 |
| 0.96.0 (LTS) | >= 22.0.0 (lts/jod) | v0.78.1 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-04 | 2027-02-04 |
| 0.95.0 | >= 22.0.0 (lts/jod) | v0.78.1 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-27 | 2026-11-27 |
| 0.94.0 (LTS) | >= 22.0.0 (lts/jod) | v0.77.2 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-20 | 2027-01-20 |
| 0.92.0 (LTS) | >= 22.0.0 (lts/jod) | v0.77.2 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-06 | 2027-01-06 |
| 0.90.0 (LTS) | >= 22.0.0 (lts/jod) | v0.76.4 | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-09-22 | 2026-12-22 |
To see a list of legacy releases, please check the legacy versions documentation page.
Troubleshooting Installation
If you experience issues installing or upgrading Solo - for example, conflicts with a previous installation - clean up your environment and reinstall:
To remove a legacy npm install or perform a full environment reset (delete Solo-managed Kind clusters and your
~/.solodirectory), see the Cleanup guide.To upgrade an existing install, install a specific version, or switch between Homebrew and npm, see Upgrading an existing Solo installation.
macOS “mounts denied” error on Apple Silicon: If
solo one-shot single deployfails immediately with a “mounts denied” or “path is not shared from the host” error, add/opt/homebrewto Docker Desktop’s File Sharing list: Settings → Resources → File Sharing → + → add/opt/homebrew→ Apply & Restart. This can occur on Apple Silicon Macs (M1/M2/M3/M4) when Homebrew’s install path (/opt/homebrew) is not included in Docker Desktop’s shared directories. Intel Mac users (Homebrew path/usr/local) are not affected.WSL2 fails to install (for example,
wsl --installreportsHCS_E_HYPERV_NOT_INSTALLED): WSL2 requires hardware virtualization and the Virtual Machine Platform feature. See Microsoft’s Install WSL guide, or use the native Windows (PowerShell) path, which does not require WSL2.First deploy fails with a PostgreSQL startup timeout: If
solo one-shot single deployfails during mirror node setup with a PostgreSQL startup timeout, this is a known intermittent issue on first deploy. Destroy the deployment and retry:solo one-shot single destroy solo one-shot single deploy
1.2 - Quickstart
Overview
Solo Quickstart provides a single, one-shot command path to deploy a running Hiero test network using the Solo CLI tool. This guide covers installing Solo, running the one-shot deployment, verifying the network, and accessing local service endpoints.
Note: This guide assumes basic familiarity with command-line interfaces and Docker.
Prerequisites
Before you begin, ensure you have completed the following:
- System Readiness:
- Prepare your local environment (Docker, Kind, Kubernetes, and related tooling) by following the System Readiness guide.
macOS prerequisite: Docker Desktop must be installed and open before running
solo one-shot single deploy. The Docker daemon is not started automatically on macOS, so confirm Docker Desktop is running from your menu bar before you begin.
Apple Silicon: If
solo one-shot single deployfails with a “mounts denied” error, see Troubleshooting Installation.
Windows (PowerShell): Complete the System Readiness Windows tab first, then run the commands on this page from a PowerShell terminal. The
soloandkubectlcommands are identical in PowerShell; only shell-specific commands (pipes, port checks, and~/.solopaths) differ, and those show a PowerShell tab.
Note: Quickstart only covers what you need to run
solo one-shot single deployand verify that the network is working. Detailed version requirements, OS-specific notes, and optional tools are documented in the System Readiness.
Step 1: Install Solo CLI
Install the latest Solo CLI globally using one of the following methods:
npm (recommended for all platforms):
npm install -g @hiero-ledger/solo@latestNote: npm requires Node.js >= 22.0.0 to already be present (check with
node --version; upgrade via nvm or nodejs.org if needed — Solo will fail with anEBADENGINEwarning on Node.js 20.x or earlier). Solo provisions kubectl, Helm, and Kind automatically at deploy time.Homebrew (deprecated — macOS/Linux/WSL2 only):
brew install hiero-ledger/tools/solo⚠️ Homebrew support is being deprecated. Solo will stop publishing updates to Homebrew after August 31, 2026. New users should install via npm. Existing Homebrew users should migrate before August 31. If you have installed solo previously by using Homebrew you should uninstall it to make sure that any new version that is installed by npm is used. Just do
brew uninstall solo.
Verify the installation
Confirm that Solo is installed and available on your PATH:
solo --version
Expected output (version may be different):
******************************* Solo *********************************************
Version : 0.84.0
**********************************************************************************
If you see a similar banner with a valid Solo version, your installation is successful.
Step 2: Deploy a local network (one-shot)
Use the one-shot command to create and configure a fully functional local Hiero network:
solo one-shot single deploy
This command performs the following actions:
- Creates or connects to a local Kubernetes cluster using Kind.
- Deploys the Solo network components.
- Sets up and funds default test accounts.
- Exposes gRPC and JSON-RPC endpoints for client access.
⏱ First-run time:
solo one-shot single deploytypically takes 3–5 minutes when container images are already cached locally, or 10–20 minutes on the very first run while Solo pulls images over the network (longer on slower connections). Long pauses with no visible output change are normal — the deploy is still running. Later deployments reuse the local image cache and complete faster. See Solo Image Cache.
Note: During deployment you may see
Stopping port-forward for port [N]printed in yellow. This is expected - as it sets up the network, Solo stops and re-establishes port-forwards to finalize the port configuration (clearing stale forwards and migrating ports as needed). It does not indicate a failure.
PostgreSQL startup timeout: If the first deployment fails during mirror node setup with a PostgreSQL startup timeout, destroy the deployment and retry — this is a known intermittent issue on first deploy:
solo one-shot single destroy solo one-shot single deploy
What gets deployed
| Component | What it does | Use it for |
|---|---|---|
| Consensus Node | Processes transactions and maintains the shared ledger. | Sending transactions and queries via a Hiero SDK. |
| Mirror Node | Indexes all transaction history and exposes a REST API and gRPC stream. | Querying balances, history, and subscribing to event feeds. |
| Explorer UI | Browser-based dashboard for inspecting accounts and transactions. | Browsing the network state without writing code. |
| JSON-RPC Relay | Ethereum-compatible JSON-RPC interface layered on top of the consensus node. | Connecting MetaMask, Hardhat, Foundry, and ethers.js. |
Multiple Node Deployment - for testing consensus scenarios
To deploy multiple consensus nodes, pass the --num-consensus-nodes flag:
solo one-shot multi deploy --num-consensus-nodes 3
This deploys 3 consensus nodes along with the same components as the single-node setup (mirror node, explorer, relay).
Note: Multiple node deployments require more resources. Ensure you have at least 16 GB of memory and 8 CPU cores allocated to Docker before running this command. See System Readiness for the full multi-node requirements.
For multi-node teardown, run solo one-shot multi destroy.
Capture your deployment name
solo one-shot single deploy (and multi deploy) assigns a unique name to
each deployment. Subsequent Solo commands and SDK guides reference it as
<your-deployment-name> — substitute your actual value when you run them.
Retrieve the most recent deployment’s name with:
solo one-shot show deployment
The output includes a Deployment Name: line - use that value as <deployment-name> in other commands.
Verify the network
After the one-shot deployment completes, verify that the Kubernetes workloads are healthy.
You can monitor the Kubernetes workloads with standard tools:
kubectl get pods -A | grep -v kube-system
kubectl get pods -A | Select-String -Pattern 'kube-system' -NotMatch
Confirm that all Solo-related pods are in a Running or Completed state.
Tip: The Solo testing team recommends k9s for managing Kubernetes clusters. It provides a terminal-based UI that makes it easy to view pods, logs, and cluster status. Install it with
brew install k9sand runk9sto launch.
Step 3: Access your local network
After the one-shot deployment completes and all pods are running, Solo sets up port-forwards so you can reach your local services. For the full endpoint reference — default ports for Solo 0.63+ and Solo 0.62 and earlier, verification commands, and port lookup — see Service Endpoints.
Open http://localhost:38080 in your browser to explore your network.
Step 4: Tear down your network
When you are finished, destroy the network to free up resources:
solo one-shot single destroy
For a full teardown procedure including failure recovery, see the Cleanup guide. For granular stop/start and management options, see Managing Your Network.
Next Steps
With your network running, connect your application or explore Solo further:
- Using Solo with Hiero SDKs — Submit transactions using the JavaScript, Java, or Go SDK.
- Using Solo with EVM Tools — Connect MetaMask, Hardhat, Foundry, or ethers.js to your local network.
- Managing Your Network — Stop, start, and reset nodes without redeploying.
- Service Endpoints — Quick reference for all default ports and connection details.
1.3 - Managing Your Network
Overview
This guide covers day-to-day management operations for a running Solo network, including starting, stopping, and restarting nodes, resetting the ledger to genesis, capturing logs, and troubleshooting.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness - your local environment meets all hardware and software requirements.
- Quickstart - you have a running Solo network deployed using
solo one-shot single deploy.
Note: If you need to upgrade an existing Solo network, see Upgrade Your Network.
solo one-shot show deployment
Expected output — the deployment name you passed to solo one-shot single deploy, or the default one-shot if you did not specify --deployment:
Deployment Name: one-shot (default)
Most management commands require your deployment name. Find it with solo one-shot show deployment — see Capture your deployment name. It defaults to one-shot unless you passed --deployment. Use it as <deployment-name> in all commands on this page.
Stopping and Starting Nodes
Important: The
solo consensus nodestop/start/restart commands act on consensus nodes only. They do not stop the mirror node, Hiero Explorer, JSON-RPC relay, block node, or the shared services (PostgreSQL, Redis, MinIO) - those keep running. Solo has no stop/start command for the non-consensus components (their lifecycle isadd/destroy). To pause the whole network without deleting any pods, see Stop the entire network.
Stop consensus nodes
Pause the consensus node(s) without destroying the deployment:
solo consensus node stop --deployment <deployment-name>
Start consensus nodes
Bring stopped consensus node(s) back online:
solo consensus node start --deployment <deployment-name>
Restart consensus nodes
Stop and start all consensus nodes in a single operation:
solo consensus node restart --deployment <deployment-name>
To verify pod status after any of the above commands, see Verify the network in the Quickstart guide.
Stop/start vs. ledger reset:
stop/start/restartpause and resume consensus nodes without touching ledger state — accounts, balances, and transaction history are preserved. To return the ledger to genesis and discard all on-ledger state, see Reset the ledger to genesis.
Stop the entire network
To pause the entire network while preserving its state - for example, to
free up memory while working on other tasks - stop the Kind cluster’s container
instead of the workloads inside it. This stops every pod without deleting any
of them, so the data on the consensus node’s emptyDir volumes (platform
software, keys, configuration, and saved state) is kept.
Find the Kind cluster container name and stop it:
docker ps --filter name=solo-cluster --format '{{.Names}}'
docker stop <container-name>
podman ps --filter name=solo-cluster --format '{{.Names}}'
podman stop <container-name>
The container name is typically solo-cluster-control-plane. On macOS and
Windows you can also do this from the Docker Desktop (or Podman Desktop)
dashboard: find the container and click Stop.
To bring the network back online, start the container and restore port-forwards:
docker start <container-name>
solo deployment port-forwards refresh --deployment <deployment-name>
podman start <container-name>
solo deployment port-forwards refresh --deployment <deployment-name>
Warning: Do not use
kubectl scale --replicas=0to stop the entire network. Scaling pods to zero deletes them, which wipes the consensus node’semptyDirvolumes. The consensus node will fail to restart correctly after scaling back up. Use the container stop/start commands above instead.
Note: To remove the network entirely (cluster, volumes, and configuration), use
solo one-shot single destroy- see the Cleanup guide.
Verify Network is Working
To confirm your Hedera network is fully operational, create a test account using the Ledger account creation command:
solo ledger account create --deployment <deployment-name>
Expected output:
*** new account created ***
-------------------------------------------------------------------------------
{
"accountId": "0.0.1001",
"publicKey": "302a300506032b6570032100439379b330f3b57b5deffda196c7c0c3387f3330a838c021954303e260606f24",
"balance": 100
}
Once the account is created, verify it in the web-based Explorer UI:
- Open your browser to http://localhost:38080
- In the search bar, enter the account ID (e.g.,
0.0.1001) - View the account details, balance, and transaction history
This confirms that:
- The network is processing transactions
- The consensus node is responding correctly
- The mirror node is indexing transactions
- The explorer is displaying data properly
Reset the ledger to genesis
To return a running deployment to a clean genesis state without tearing it down and redeploying, reset the ledger system. This clears the saved consensus state and ledger-related secrets, returning the ledger to genesis - with no accounts, files, or balances beyond the genesis defaults:
solo ledger system reset --deployment <deployment-name>
solo ledger system reset is the counterpart to solo ledger system init
(which initializes a new deployment). Use it when you want a fresh ledger - for
example, to rerun a scenario from a known starting point - while keeping the
same Kind cluster and deployment.
| Flag | Description |
|---|---|
--deployment | The deployment to reset. |
--node-aliases | Comma-separated consensus node aliases to reset. Defaults to all nodes in the deployment. |
--cluster-ref | The cluster reference, for a deployment that spans multiple clusters. |
Note: This discards on-ledger state created since genesis and cannot be undone. It does not delete the cluster or deployment - to remove those entirely, use
solo one-shot single destroy(see the Cleanup guide).
Viewing Logs
To capture logs and diagnostic information for your deployment:
solo deployment diagnostics all --deployment <deployment-name>
Logs are saved to ~/.solo/logs/ (on native Windows, $env:USERPROFILE\.solo\logs\).
Expected output:
******************************* Solo *********************************************
Version : 0.59.1
Kubernetes Context : kind-solo
Kubernetes Cluster : kind-solo
Current Command : deployment diagnostics all --deployment <deployment-name>
**********************************************************************************
✔ Initialize [0.3s]
✔ Get consensus node logs and configs [15s]
✔ Get Helm chart values from all releases [2s]
✔ Downloaded logs from 10 Hiero component pods [1s]
✔ Get node states [10s]
Configurations and logs saved to /Users/<username>/.solo/logs
Log zip file network-node1-0-log-config.zip downloaded to /Users/<username>/.solo/logs/<deployment-name>
Helm chart values saved to /Users/<username>/.solo/logs/helm-chart-values
You can also retrieve logs for a specific pod directly using kubectl:
kubectl logs -n <namespace> <pod-name>
Important: Solo deploys each network into a Kubernetes namespace. For one-shot deployments, the namespace defaults to
one-shot(matching the default deployment name). You can override it by passing--namespacetosolo one-shot single deploy.
To find your deployment namespace, use any of:
# Look up the namespace Solo recorded for this deployment
solo deployment config info --deployment <deployment-name>
# Or list all namespaces and pick the one matching your deployment
kubectl get ns
# Or inspect pods and use the NAMESPACE column
kubectl get pods -A | grep -v kube-system
For one-shot deployments the namespace matches the deployment name, which defaults to one-shot unless you passed --deployment (retrieve it with solo one-shot show deployment).
Replace <namespace> and <pod-name> with the values from your deployment.
1.4 - Upgrade Your Network
Overview
This guide explains how to upgrade an existing local Solo network deployment to a newer Hiero version. It is intended for networks that were already deployed with solo one-shot single deploy.
Note: If you just completed Quickstart with the latest Solo release, you do not need to upgrade unless you are intentionally moving an older deployment to a newer version.
Prerequisites
Before upgrading, ensure you have completed the following:
- Quickstart - you have already deployed a running Solo network using
solo one-shot single deploy. - System Readiness - your local environment meets Solo requirements.
- A currently running Solo deployment to upgrade.
Step 1: Find your deployment name
The default for one-shot deployments is one-shot. If you used a different name, find it with solo one-shot show deployment (see Capture your deployment name). Use that value as <deployment-name> in the upgrade command.
Step 2: Upgrade the network
Run the following command to upgrade an existing Solo network deployment to a newer Hiero version:
solo consensus network upgrade --deployment <deployment-name> --upgrade-version <version>
Replace <version> with the target Hiero version, for example v0.59.0.
Important: This command is only for networks already deployed with Solo. Do not run it immediately after Quickstart unless you are moving an older deployment to a newer version.
Apply updated fee schedules and throttles
By default, an upgrade does not change the network’s fee schedule (system file
0.0.113) or throttles (system file 0.0.123). They keep the content they had
before, including any customizations. To replace them as part of the upgrade,
pass the new files:
solo consensus network upgrade --deployment <deployment-name> --upgrade-version <version> \
--simple-fees-schedules-file ./simpleFeesSchedules.json \
--throttles-file ./throttles.json
Each flag is optional, so you can pass either file on its own. Keep the following in mind:
- Use the files from the release you are upgrading to. A node rejects files
that reference transaction types it does not know, and keeps its previous
file. Download them from the
hiero-consensus-noderepository at the matching tag, underhedera-node/configuration/mainnet/upgrade/, for examplehttps://raw.githubusercontent.com/hiero-ledger/hiero-consensus-node/<version>/hedera-node/configuration/mainnet/upgrade/simpleFeesSchedules.json. - Files apply only during a version upgrade. Upgrading to the version the network already runs does not apply them.
- Each upgrade applies only the files passed to it. An upgrade without these flags leaves the current fee schedule and throttles as they are.
- Minimum versions.
--simple-fees-schedules-filerequires a target version of v0.68.0 or later, and--throttles-filev0.54.0 or later. Both require Solo v0.XX.0 or later. - Not with
--upgrade-zip-file. If you supply your own upgrade zip, place the files underdata/config/inside it instead.
If topic messages fail with FAIL_INVALID after an upgrade, see
Topic messages fail with FAIL_INVALID after a network upgrade.
Step 3: Verify the upgrade
After upgrading, confirm the network is healthy by checking pod status:
kubectl get pods -n <namespace>
For one-shot deployments, the namespace matches the deployment name, which defaults to one-shot unless you passed --deployment (retrieve it with solo one-shot show deployment).
1.5 - Upgrading an existing Solo installation
Overview
If you already have Solo installed, upgrade to the latest release using the same package manager you originally installed with. This page covers the Homebrew and npm upgrade paths, switching between them, and a clean-reinstall recipe for when an upgrade leaves Solo in a broken state.
⚠️ Homebrew support is being deprecated. Solo will stop publishing updates to Homebrew after August 31, 2026. Existing Homebrew users should migrate to npm before August 31. See Switching between Homebrew and npm.
Tip: Check your current version first with
solo --version, and compare it against the latest release on the Solo releases page.
Upgrade a Homebrew install
If you installed Solo with brew install hiero-ledger/tools/solo, update
Homebrew’s formula list and upgrade:
brew update
brew upgrade hiero-ledger/tools/solo
brew update refreshes Homebrew’s formulae; brew upgrade then installs the
latest Solo (and Node.js, its only Homebrew dependency). Verify the new
version:
solo --version
Upgrade an npm install
If you installed Solo with npm, re-run the global install with the @latest tag
to move to the newest release:
npm install -g @hiero-ledger/solo@latest
Note: Unlike the Homebrew formula, npm does not install Node.js - make sure Node.js is present before upgrading. (Solo provisions kubectl, Helm, and Kind automatically at deploy time regardless of install method.) After a major-version upgrade, re-check the required tool versions in System Readiness.
Resolving an EEXIST package-name conflict
Solo is published to npm under two package names - @hiero-ledger/solo and
@hashgraph/solo - that are mirrors of the same tool. Both install the same
solo command-line binary, so only one can be globally installed at a time. If
you already installed Solo under one name and then install it under the other,
npm refuses to overwrite the existing binary and the install fails with
EEXIST:
npm error code EEXIST
npm error path /Users/user/.nvm/versions/node/v22.14.0/bin/solo
npm error EEXIST: file already exists
npm error File exists: /Users/user/.nvm/versions/node/v22.14.0/bin/solo
npm error Remove the existing file and try again, or run npm with --force to overwrite files recklessly.
This is expected npm behavior - npm will not overwrite a binary owned by a different package name. To resolve it, uninstall the other package first, then install the one you want:
# Switching to the @hiero-ledger namespace
npm uninstall -g @hashgraph/solo
npm install -g @hiero-ledger/solo@latest
Note: If you installed under
@hiero-ledger/soloand want to move to@hashgraph/solo, swap the names in the commands above.
If the install still reports EEXIST after uninstalling - for example because
an orphaned solo binary was left behind - remove the leftover binary and
reinstall:
rm "$(which solo)"
npm install -g @hiero-ledger/solo@latest
Tip: To remove every npm copy of Solo regardless of namespace, see Clean up legacy npm installations.
Install a specific version
To install a specific (non-latest) Solo release - for example, to reproduce a
bug, run a regression test, or pin a version across a team - use a versioned
Homebrew formula or npm tag instead of latest.
Note: A versioned brew formula or npm tag pins Solo to that release - it will not move when you run
brew upgradeornpm update. To change versions later (including returning to the latest release, or downgrading), switching in place is not supported: uninstall Solo first (brew uninstall hiero-ledger/tools/solo, ornpm uninstall -g @hiero-ledger/solo), then run the versioned install command below for the version you want. This keeps your~/.solodata - only a Clean reinstall removes it. If you are switching package managers, see also Switching between Homebrew and npm.
brew install hiero-ledger/tools/solo@0.76.0
The tap publishes a versioned formula (solo@<version>) for each release.
npm install -g @hiero-ledger/solo@0.76.0
Note: On Solo v0.74.0 and later, a global install - including a pinned version - automatically pre-pulls that version’s container images into the image cache (
~/.solo/cache/images/), which can take a few minutes and several GB on first run. SetSOLO_NO_CACHE=true(npm) orHOMEBREW_NO_SOLO_CACHE(Homebrew) to skip it.
Confirm the installed version:
solo --version
Tip: Installing a versioned formula or npm tag pins Solo to that release - it will not move when you run
brew upgradeornpm update. To return to the latest release, follow Upgrade a Homebrew install or Upgrade an npm install above. If you hit a “twosolobinaries on PATH” conflict when switching, remove the other install first (see Switching between Homebrew and npm).
Switching between Homebrew and npm
To migrate from Homebrew to npm, remove the Homebrew copy first so you do not
end up with two solo binaries on your PATH:
# Remove the Homebrew copy before installing via npm
brew uninstall hiero-ledger/tools/solo
Then install via npm following the steps in System Readiness.
Clean reinstall
If an upgrade leaves Solo in a broken state - for example, conflicts from an
older install or a partially migrated ~/.solo - remove Solo and its
configuration, then reinstall.
Warning: This deletes your Solo home directory (
~/.solo), including the image cache, cached configuration, and logs. The reinstall step below re-pulls the image cache (a few minutes, several GB) on Solo v0.74.0 and later. Destroy any running deployments first withsolo one-shot single destroy- see the Cleanup guide.
brew uninstall hiero-ledger/tools/solo
rm -rf ~/.solo
brew install hiero-ledger/tools/solo
npm uninstall -g @hiero-ledger/solo
rm -rf ~/.solo
npm install -g @hiero-ledger/solo@latest
Confirm the reinstall:
solo --version
For additional cleanup options - removing a legacy npm install, Solo-managed Kind clusters, and other artifacts - see the Cleanup guide.
1.6 - Cleanup
Overview
This guide covers how to tear down a Solo network deployment, understand resource usage, and perform a full reset when needed.
Prerequisites
Before proceeding, ensure you have completed the following:
- Quickstart — you have a running Solo
network deployed using
solo one-shot single deploy.
Destroying Your Network
Important: Always destroy your network before deploying a new one to avoid conflicts and errors.
To remove your Solo network:
solo one-shot single destroy
For multi-node one-shot deployments, use:
solo one-shot multi destroy
This command performs the following actions:
- Uninstalls all component Helm releases (consensus, mirror, relay, explorer).
- Removes the Solo cluster chart and disconnects the cluster reference.
- Deletes the deployment from Solo’s local configuration and clears the cache.
- Does NOT delete the Kind cluster - the cluster persists after destroy.
Failure modes and rerunning destroy
If solo one-shot single destroy fails part-way through (for example, due to an
earlier deploy error), some resources may remain:
- The Solo namespace or one or more PVCs may not be deleted, which can leave Docker volumes appearing as “in use”.
- The destroy commands are designed to be idempotent, so you can safely rerun
solo one-shot single destroyto complete cleanup.
If rerunning destroy does not release the resources, use the Full Reset procedure below to force a clean state.
Remove the Kind cluster
solo one-shot single destroy intentionally leaves the Kind cluster in Docker
so you can redeploy quickly. If you want a completely clean slate, delete the
cluster after destroying the deployment:
kind delete cluster --name solo-cluster
solo-cluster is Solo’s default Kind cluster name; run kind get clusters to
confirm yours if you used a custom name. To also remove Solo’s local
configuration and cache, use the Full Reset procedure.
Resource Usage
Solo deploys a fully functioning mirror node that stores the transaction history generated by your local test network. During active testing, the mirror node’s resource consumption will grow as it processes more transactions. If you notice increasing resource usage, destroy and redeploy the network to reset it to a clean state.
Full Reset
Warning: This is a last resort procedure. Only use the Full Reset if
solo one-shot single destroyfails or your Solo state is corrupted. For normal teardown, always usesolo one-shot single destroyinstead.
# Delete only Solo-managed Kind clusters (names starting with "solo")
kind get clusters | grep '^solo' | while read cluster; do
kind delete cluster -n "$cluster"
done
# Remove Solo configuration and cache
rm -rf ~/.solo
Warning: The commands above will delete all Solo-managed Kind clusters and remove your Solo home directory (
~/.solo). Always use thegrep '^solo'filter when listing clusters - omitting it will delete every Kind cluster on your machine, including any unrelated to Solo.
After deleting the Kind cluster, Kubernetes resources (including namespaces and PVCs) and their associated volumes should be released. If Docker still reports unused volumes that you want to remove, you can optionally run:
# Optional: remove all unused Docker volumes
docker volume prune
Warning:
docker volume pruneremoves all unused Docker volumes on your machine, not just those created by Solo. Only run this command if you understand its impact.
- To redeploy after a full reset, follow the Quickstart guide.
Clean up legacy npm installations
If you previously installed Solo via npm (for example, from older workshops or
documentation), remove the global package to avoid conflicts with a newer npm
install. Solo has been published under two npm names — @hiero-ledger/solo and
@hashgraph/solo — so remove both to be sure no copy is left behind:
# Remove any npm-based Solo install (safe to run even if not present)
npm uninstall -g @hiero-ledger/solo
npm uninstall -g @hashgraph/solo
Then reinstall using the Quickstart, or follow Upgrading an existing Solo installation to move to a specific or latest version.
Tip: If an install failed with
EEXIST: file already existsbecause both package names were present, see Resolving anEEXISTpackage-name conflict.
2 - Advanced Solo Setup
A comprehensive reference of all environment variables supported by Solo, including their purposes, default values, and expected formats. Configure Solo deployments through environment variable tuning.
Step-by-step workflows and component-level customization for users who need full control over network initialization, configuration, and scaling. Explore YAML-driven deployments, manual orchestration, dynamic node management, and extensive reference documentation.
Learn how to attach a JVM debugger to a running Hiero Consensus Node, retrieve logs for analysis, and save and restore network state files along with essential tools for developers and deep-level troubleshooting.
How Solo decides which environment variables reach the external commands it runs (helm, kubectl, kind, container engines), how to tell when a variable was withheld, and how to forward an additional variable when a platform requires one.
Use the –edge flag and *_EDGE_VERSION environment variables to deploy a Solo network against arbitrary component versions — release candidates, pre-releases, or local builds — without modifying Solo source or rebuilding the CLI.
Use the Task runner to deploy and customize Solo networks, then explore maintained GitHub example projects for common workflows.
Integrate Solo into a GitHub Actions CI pipeline. Covers GitHub-hosted runners (ubuntu-latest) and self-hosted runners, including runner requirements, tool installation, and automated network deployment.
Run Solo E2E performance tests locally, including setup, execution, optional local build path configuration, and branch workflow triggering.
Canonical Solo CLI command and flag reference, including migration guidance from legacy command paths. Use this section to look up Solo commands, subcommands, and flags.
Speed up deployments by pre-pulling and reusing the container images Solo needs. Manage the local image cache with the solo cache image commands, and control automatic caching during install and one-shot deployments.
Speed up deployments by pre-pulling and reusing the Helm charts Solo installs. Manage the local chart cache with the solo cache chart commands, and let deploys install charts from disk instead of the network.
2.1 - Using Environment Variables
Overview
Solo supports a set of environment variables that let you customize its behaviour without modifying command-line flags on every run. Variables set in your shell environment take effect automatically for all subsequent Solo commands.
The variables on this page configure Solo itself. They are not the same as the
variables Solo passes on to the external tools it runs (helm, kubectl, kind).
Those are filtered by an allowlist — see
Subprocess Environment Filtering
if a variable you set is not reaching one of those tools.
Setting environment variables
How you set a variable depends on your shell. Use the tab for your platform:
# For a single command only
CONSENSUS_NODE_VERSION=v0.73.0 solo one-shot single deploy
# For the current session
export CONSENSUS_NODE_VERSION=v0.73.0
# Persist across sessions (add to ~/.bashrc or ~/.zshrc)
echo 'export CONSENSUS_NODE_VERSION=v0.73.0' >> ~/.zshrc
# For the current session
$env:CONSENSUS_NODE_VERSION = 'v0.73.0'
# Persist for your user (all future sessions)
[System.Environment]::SetEnvironmentVariable('CONSENSUS_NODE_VERSION', 'v0.73.0', 'User')
# Or add it to your PowerShell profile
Add-Content $PROFILE '$env:CONSENSUS_NODE_VERSION = "v0.73.0"'
Tip: Variables set in your shell environment (or persisted as shown above) take effect automatically for all subsequent Solo commands.
General
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_HOME | Path to the Solo cache and log files | ~/.solo |
SOLO_CACHE_DIR | Path to the Solo cache directory | ~/.solo/cache |
SOLO_LOG_LEVEL | Logging level for Solo operations. Accepted values: trace, debug, info, warn, error | info |
SOLO_DEV_OUTPUT | Treat all commands as if the --debug flag were specified (--debug was formerly --dev) | false |
SOLO_CHAIN_ID | Chain ID of the Solo network | 298 |
FORCE_PODMAN | Force the use of Podman as the container engine when creating a new local cluster. Accepted values: true, false | false |
KUBECONFIG | Kubeconfig file, or :-separated list of files, that Solo uses to reach your clusters. When Solo creates the local cluster with rootful Podman on Linux, kind writes the kind-kind cluster, context and user into the first listed file that exists, else into the last listed file | ~/.kube/config |
Network and Node Identity
| Environment Variable | Description | Default Value |
|---|---|---|
DEFAULT_START_ID_NUMBER | Raw node ID number for the first consensus node. The first node account ID is resolved as 0.0.<DEFAULT_START_ID_NUMBER> | 3 |
SOLO_NODE_INTERNAL_GOSSIP_PORT | Internal gossip port used by the Hiero network | 50111 |
SOLO_NODE_EXTERNAL_GOSSIP_PORT | External gossip port used by the Hiero network | 50111 |
SOLO_NODE_DEFAULT_STAKE_AMOUNT | Default stake amount for a node | 500 |
GRPC_PORT | Local port-forward for consensus node gRPC. Default is 35211 for Solo 0.63+ (changed from 50211 to avoid Windows ephemeral-port conflicts). See Port availability. | 35211 |
LOCAL_NODE_START_PORT | Local node start port for the Solo network | 30212 |
NETWORK_NODE_LIFECYCLE_MODE | Selects the root container image Solo uses to run each consensus node and how it starts and stops the node process. Accepted values: solo-container (the solo-containers image, controlled by its /command/network-node-lifecycle helper) and consensus-node-image (the hiero-consensus-node deterministic image gcr.io/hedera-registry/consensus-node:<version>, whose platform jars are baked in and which Solo controls with s6-svc). In consensus-node-image mode Solo sets AUTO_START_CONSENSUS_SERVICE=false, skips the Fetch platform software step, and installs zip, unzip and curl in the root container. Version upgrade (solo consensus network upgrade) is not supported in consensus-node-image mode yet | solo-container |
Operator and Key Configuration
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_OPERATOR_ID | Operator account ID for the Solo network | 0.0.2 |
SOLO_OPERATOR_KEY | Operator private key for the Solo network | 302e020100... |
SOLO_OPERATOR_PUBLIC_KEY | Operator public key for the Solo network | 302a300506... |
FREEZE_ADMIN_ACCOUNT | Freeze admin account ID for the Solo network | 0.0.58 |
GENESIS_KEY | ED25519 genesis private key for a new Solo network. At solo consensus network deploy Solo stores it in the genesis-key Kubernetes secret and sets the genesis public key of the consensus nodes to match. Later commands read the secret first, then this variable | 302e020100... |
Note: Full key values are omitted above for readability. Refer to the source defaults for complete key strings.
Node Client Behaviour
| Environment Variable | Description | Default Value |
|---|---|---|
NODE_CLIENT_MIN_BACKOFF | Minimum wait time between retries, in milliseconds | 1000 |
NODE_CLIENT_MAX_BACKOFF | Maximum wait time between retries, in milliseconds | 1000 |
NODE_CLIENT_REQUEST_TIMEOUT | Time a transaction or query retries on a “busy” network response, in milliseconds | 600000 |
NODE_CLIENT_MAX_ATTEMPTS | Maximum number of attempts for node client operations | 600 |
NODE_CLIENT_SDK_PING_MAX_RETRIES | Maximum number of retries for node health pings | 5 |
NODE_CLIENT_SDK_PING_RETRY_INTERVAL | Interval between node health ping retries, in milliseconds | 10000 |
NODE_COPY_CONCURRENT | Number of concurrent threads used when copying files to a node | 4 |
EXPERIMENTAL_COPY_WRAPS_LIB_IN_PARALLEL | Copy the WRAPS proving-key library to every consensus node concurrently during solo network deploy, instead of one node at a time. Concurrent copies finish faster on a network deploy with many nodes and ample bandwidth, but can saturate a constrained connection when several multi-hundred-megabyte copies run at once. Accepted values: true, false | false |
LOCAL_BUILD_COPY_RETRY | Number of retries for local build copy operations | 3 |
ACCOUNT_UPDATE_BATCH_SIZE | Number of accounts to update in a single batch operation | 10 |
Pod and Network Readiness
| Environment Variable | Description | Default Value |
|---|---|---|
PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if pods are running | 900 |
PODS_RUNNING_DELAY | Interval between pod running checks, in milliseconds | 1000 |
PODS_READY_MAX_ATTEMPTS | Maximum number of attempts to check if pods are ready | 300 |
PODS_READY_DELAY | Interval between pod ready checks, in milliseconds | 2000 |
NETWORK_NODE_ACTIVE_MAX_ATTEMPTS | Maximum number of attempts to check if network nodes are active | 300 |
NETWORK_NODE_ACTIVE_DELAY | Interval between network node active checks, in milliseconds | 1000 |
NETWORK_NODE_ACTIVE_TIMEOUT | Maximum wait time for network nodes to become active, in milliseconds | 1000 |
NETWORK_PROXY_MAX_ATTEMPTS | Maximum number of attempts to check if the network proxy is running | 300 |
NETWORK_PROXY_DELAY | Interval between network proxy checks, in milliseconds | 2000 |
NETWORK_DESTROY_WAIT_TIMEOUT | Maximum wait time for network teardown to complete, in milliseconds | 120 |
STATE_DOWNLOAD_STABLE_MAX_ATTEMPTS | Maximum number of attempts to check whether a consensus node’s saved state has stopped changing on disk, before solo consensus state download archives it and before solo consensus network freeze stops the nodes | 180 |
STATE_DOWNLOAD_STABLE_DELAY | Interval between saved state stability checks, in milliseconds | 2000 |
STATE_DOWNLOAD_STABLE_POLLS_REQUIRED | Number of consecutive checks that must report an unchanged saved state before it is treated as stable | 3 |
Block Node
| Environment Variable | Description | Default Value |
|---|---|---|
BLOCK_NODE_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if block node pods are running | 900 |
BLOCK_NODE_PODS_RUNNING_DELAY | Interval between block node pod running checks, in milliseconds | 1000 |
BLOCK_NODE_ACTIVE_MAX_ATTEMPTS | Maximum number of attempts to check if block nodes are active | 100 |
BLOCK_NODE_ACTIVE_DELAY | Interval between block node active checks, in milliseconds | 60 |
BLOCK_NODE_ACTIVE_TIMEOUT | Maximum wait time for block nodes to become active, in milliseconds | 60 |
BLOCK_STREAM_STREAM_MODE | The blockStream.streamMode value in consensus node application properties. Only applies when a Block Node is deployed | BOTH |
BLOCK_STREAM_WRITER_MODE | The blockStream.writerMode value in consensus node application properties. Only applies when a Block Node is deployed | FILE_AND_GRPC |
Relay Node
| Environment Variable | Description | Default Value |
|---|---|---|
RELAY_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if relay pods are running | 900 |
RELAY_PODS_RUNNING_DELAY | Interval between relay pod running checks, in milliseconds | 1000 |
RELAY_PODS_READY_MAX_ATTEMPTS | Maximum number of attempts to check if relay pods are ready | 100 |
RELAY_PODS_READY_DELAY | Interval between relay pod ready checks, in milliseconds | 1000 |
Mirror Node
| Environment Variable | Description | Default Value |
|---|---|---|
DISABLE_IMPORTER_SPRING_PROFILES | Disable automatic configuration of Mirror Node importer Spring profiles for block-node integration. | false |
SPRING_PROFILES_ACTIVE | Spring profiles to use for the Mirror Node importer when automatic importer profile configuration is enabled. | blocknode |
MIRROR_NODE_SCHEMA_READY_MAX_ATTEMPTS | Maximum number of attempts to check if the Mirror Node database schema has been built (signalled by importer pod readiness) | 900 |
MIRROR_NODE_SCHEMA_READY_DELAY | Interval between Mirror Node database schema checks, in milliseconds | 2000 |
MIRROR_NODE_IMPORTER_DETECT_MAX_ATTEMPTS | Maximum number of attempts to detect a running Mirror Node importer pod. If no importer pod is found, the database schema wait is skipped | 15 |
MIRROR_NODE_IMPORTER_DETECT_DELAY | Interval between Mirror Node importer pod detection attempts, in milliseconds | 2000 |
MIRROR_NODE_CHART_UPGRADE_MAX_ATTEMPTS | Maximum number of attempts to install or upgrade the Mirror Node Helm chart before failing. Retries ride out transient Kubernetes API server outages | 3 |
MIRROR_NODE_CHART_UPGRADE_RETRY_DELAY_SECS | Delay between Mirror Node Helm chart install/upgrade attempts, in seconds | 15 |
MIRROR_EXTERNAL_DATABASE_CLIENT_IMAGE | Image of the short-lived psql pod that mirror node add / mirror node upgrade with --use-external-database starts to grant the readonly role to mirror_rest on the external database. The image must provide psql and sleep. Override it for private or air-gapped registries | docker.io/bitnamilegacy/postgresql-repmgr:17.6.0-debian-12-r2 |
Load Balancer
| Environment Variable | Description | Default Value |
|---|---|---|
LOAD_BALANCER_CHECK_DELAY_SECS | Delay between load balancer status checks, in seconds | 5 |
LOAD_BALANCER_CHECK_MAX_ATTEMPTS | Maximum number of attempts to check load balancer status | 60 |
Lease Management
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_LEASE_ACQUIRE_ATTEMPTS | Number of attempts to acquire a lock before failing | 10 |
SOLO_LEASE_DURATION | Duration in seconds for which a lock is held before expiration | 20 |
Component Versions
| Environment Variable | Description |
|---|---|
CONSENSUS_NODE_VERSION | Release version of the Consensus Node to use |
BLOCK_NODE_VERSION | Release version of the Block Node to use |
MIRROR_NODE_VERSION | Release version of the Mirror Node to use |
EXPLORER_VERSION | Release version of the Explorer to use |
RELAY_VERSION | Release version of the JSON-RPC Relay to use |
INGRESS_CONTROLLER_VERSION | Release version of the HAProxy Ingress Controller to use |
SOLO_CHART_VERSION | Release version of the Solo Helm charts to use |
SOLO_CHEETAH_VERSION | Image version for the solo-deployment chart’s Cheetah component |
SOLO_CONTAINERS_VERSION | Image version for the solo-deployment chart’s Solo containers component |
MINIO_OPERATOR_VERSION | Release version of the MinIO Operator to use |
PROMETHEUS_STACK_VERSION | Release version of the Prometheus Stack to use |
GRAFANA_ALLOY_VERSION | Helm chart version of Grafana Alloy installed by solo cluster-ref config setup --grafana-alloy |
LOKI_VERSION | Helm chart version of the Loki log store installed by solo cluster-ref config setup --grafana-alloy |
GRAFANA_PODLOGS_CRD_VERSION | Grafana Alloy release tag the PodLogs custom resource definition is fetched from during solo network deploy --enable-monitoring-support |
Tip: To pin component versions for a
solo one-shot single deploy, prefix the command with these variables. See the One-Shot Deployment section below for an example.
Edge Component Versions
These variables only take effect when solo one-shot single deploy or
solo one-shot multi deploy is invoked with the --edge flag (solo one-shot falcon deploy does not accept --edge in v0.72.0). They let you point a
one-shot deploy at arbitrary component tags — release candidates,
pre-releases, or any other tag the component’s registry exposes — without
rebuilding Solo.
| Component | Environment Variable | Falls back to |
|---|---|---|
| Consensus Node | CONSENSUS_NODE_EDGE_VERSION | CONSENSUS_NODE_VERSION |
| Mirror Node | MIRROR_NODE_EDGE_VERSION | MIRROR_NODE_VERSION |
| JSON-RPC Relay | RELAY_EDGE_VERSION | RELAY_VERSION |
| Explorer | EXPLORER_EDGE_VERSION | EXPLORER_VERSION |
| Block Node | BLOCK_NODE_EDGE_VERSION | BLOCK_NODE_VERSION |
| Solo Chart | SOLO_CHART_EDGE_VERSION | SOLO_CHART_VERSION |
Set only the variables for components you want to override; the rest use their
compiled-in edge defaults. Without --edge, every *_EDGE_VERSION variable is
ignored.
For full usage, examples, version-format rules, and troubleshooting, see One-Shot Deploy with Custom Component Versions.
Helm Chart URLs
| Environment Variable | Description | Default Value |
|---|---|---|
JSON_RPC_RELAY_CHART_URL | Helm chart repository URL for the JSON-RPC Relay | https://hiero-ledger.github.io/hiero-json-rpc-relay/charts |
MIRROR_NODE_CHART_URL | Helm chart repository URL for the Mirror Node | https://hashgraph.github.io/hedera-mirror-node/charts |
EXPLORER_CHART_URL | Helm chart repository URL for the Explorer | oci://ghcr.io/hiero-ledger/hiero-mirror-node-explorer/hiero-explorer-chart |
INGRESS_CONTROLLER_CHART_URL | Helm chart repository URL for the ingress controller | https://haproxy-ingress.github.io/charts |
PROMETHEUS_OPERATOR_CRDS_CHART_URL | Helm chart repository URL for the Prometheus Operator CRDs | https://prometheus-community.github.io/helm-charts |
GRAFANA_ALLOY_CHART_URL | Helm chart repository URL for Grafana Alloy | https://grafana.github.io/helm-charts |
LOKI_CHART_URL | Helm chart repository URL for Loki | https://grafana.github.io/helm-charts |
NETWORK_LOAD_GENERATOR_CHART_URL | Helm chart repository URL for the Network Load Generator | oci://swirldslabs.jfrog.io/load-generator-helm-release-local |
Local Helm Chart Directories
Chart owners can test an unpublished chart by pointing Solo at a local chart
directory. Only the chart templates are local: every container image the chart
references must already be pullable by the cluster (published to a registry or
loaded with kind load docker-image). These variables are the equivalent of the
--block-node-chart-dir, --explorer-chart-dir, --mirror-node-chart-dir and
--relay-chart-dir flags, and the flag takes precedence when both are set.
| Environment Variable | Description | Default Value |
|---|---|---|
SOLO_BLOCK_NODE_CHART_DIR | Directory that contains the block node chart (block-node-server), e.g. /path/to/hiero-block-node/charts | unset (published chart) |
SOLO_EXPLORER_CHART_DIR | The explorer chart directory itself (the one holding Chart.yaml), e.g. /path/to/hiero-mirror-node-explorer/_frontend/chart | unset (published chart) |
SOLO_MIRROR_NODE_CHART_DIR | Directory that contains the mirror node chart (hedera-mirror), e.g. /path/to/hiero-mirror-node/charts | unset (published chart) |
SOLO_RELAY_CHART_DIR | Directory that contains the JSON-RPC relay chart (hedera-json-rpc), e.g. /path/to/hiero-json-rpc-relay/charts | unset (published chart) |
Note: The explorer variable takes the chart directory itself, while the other three take the directory that contains the chart. Use absolute paths: Solo does not expand
~inside the value.
For example, to deploy a network with a local mirror node chart:
SOLO_MIRROR_NODE_CHART_DIR=/path/to/hiero-mirror-node/charts solo one-shot single deploy
Network Load Generator
| Environment Variable | Description | Default Value |
|---|---|---|
NETWORK_LOAD_GENERATOR_CHART_VERSION | Release version of the Network Load Generator Helm chart to use | v0.7.0 |
NETWORK_LOAD_GENERATOR_PODS_RUNNING_MAX_ATTEMPTS | Maximum number of attempts to check if Network Load Generator pods are running | 900 |
NETWORK_LOAD_GENERATOR_POD_RUNNING_DELAY | Interval between Network Load Generator pod running checks, in milliseconds | 1000 |
One-Shot Deployment
| Environment Variable | Description | Default Value |
|---|---|---|
ONE_SHOT_WITH_BLOCK_NODE | Deploy Block Node as part of a one-shot deployment | false |
MIRROR_NODE_PINGER_TPS | Transactions per second for the Mirror Node monitor pinger. Set to 0 to disable | 5 |
CONSENSUS_NODE_EDGE_VERSION | Edge (newer-than-default) consensus node version used by --edge in one-shot deploys. Falls back to CONSENSUS_NODE_VERSION. | v0.74.0-rc.1 |
MIRROR_NODE_EDGE_VERSION | Edge mirror node version used by --edge in one-shot deploys. Falls back to MIRROR_NODE_VERSION. | v0.153.1 |
EXPLORER_EDGE_VERSION | Edge explorer version used by --edge in one-shot deploys. Falls back to EXPLORER_VERSION. | 26.0.0 |
RELAY_EDGE_VERSION | Edge relay version used by --edge in one-shot deploys. Falls back to RELAY_VERSION. | 0.76.2 |
BLOCK_NODE_EDGE_VERSION | Edge block node version used by --edge in one-shot deploys. Falls back to BLOCK_NODE_VERSION. | 0.31.0 |
Pinning Component Versions
solo one-shot single deploy does not yet expose CLI flags for pinning
individual component versions. To run a one-shot deployment against specific
releases, prefix the command with the
Component Versions environment variables:
CONSENSUS_NODE_VERSION=v0.73.0 MIRROR_NODE_VERSION=v0.153.1 solo one-shot single deploy
Any of the *_VERSION variables listed in
Component Versions can be combined in the same command
to pin multiple components at once.
Note:
- This is the current recommended approach for version pinning in one-shot deployments.
- CLI flags for version overrides on
one-shotare planned for Q2 — tracked in hiero-ledger/solo#4242.- Environment variables will remain valid for one-off overrides after the CLI flags land, so the form above will continue to work.
Image Cache
Solo caches the container images it deploys as local archives to speed up
repeat deployments. The cache is enabled by default; these variables disable it
per context. See Solo Image Cache for
the full feature and the solo cache image commands.
| Environment Variable | Description | Default |
|---|---|---|
ENABLE_IMAGE_CACHE | Set to false to disable the image cache during solo one-shot deploys. Requires Solo v0.78.0 or later (earlier releases have an inverted-logic bug in this flag). | enabled |
SOLO_NO_CACHE | Set to true to skip the image pull during an npm global install. | enabled |
HOMEBREW_NO_SOLO_CACHE | Set to any value to skip the image pull during a Homebrew install. | enabled |
CACHE_IMAGE_MAX_CONCURRENCY | Max concurrent image cache pull/load operations | 12 |
Note: The cached component versions follow the same environment-variable mechanism as Pinning Component Versions above - the
*_VERSIONenvironment variables affect the images the cache pulls, but the--*-versionCLI flags do not.
2.2 - Network Deployments
Deploy a complete Solo network from a single YAML file for repeatable advanced setups, CI pipelines, and custom component configuration. Falcon combines simplicity with full customization using the Solo values file format.
Comprehensive reference for all supported CLI flags per section of a Falcon values file, including defaults, types, and descriptions. Use this as your source of truth when customizing Falcon deployments.
Deploy each Solo network component individually for maximum control over configuration and debugging. Execute each step manually through the Solo CLI and integrate Solo into bespoke automation pipelines.
Configure consensus node application.properties with Solo’s default merge mode or full overwrite mode.
Learn how to dynamically add, update, and remove consensus nodes in a running Solo network without taking the network offline. Execute operations independently while the network remains operational.
Pass environment variables to the consensus node JVM with an application.env file and the –application-env flag.
2.2.1 - One-shot Falcon Deployment
Overview
One-shot Falcon deployment is Solo’s YAML-driven one-shot workflow. It uses the same core
deployment pipeline as solo one-shot single deploy, but lets you inject
component-specific flags through a single values file.
Use One-shot Falcon deployment when you need a repeatable advanced setup, want to check a complete deployment into source control, or need to customise component flags without running every Solo command manually.
Falcon is especially useful for:
- CI/CD pipelines and automated test environments.
- Reproducible local developer setups.
- Advanced deployments that need custom chart paths, image versions, ingress, storage, TLS, or node startup options.
Important: Falcon is an orchestration layer over Solo’s standard commands. It does not introduce a separate deployment model. Solo still creates a deployment, attaches clusters, deploys the network, configures nodes, and then adds optional components such as mirror node, explorer, and relay.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness - your local environment meets the hardware and software requirements for Solo, Kubernetes, Docker, Kind, kubectl, and Helm.
- Quickstart -you are already familiar with the standard one-shot deployment workflow.
How Falcon Works
When you run Falcon deployment, Solo executes the same end-to-end deployment sequence used by its one-shot workflows:
- Connect to the Kubernetes cluster.
- Create a deployment and attach the cluster reference.
- Set up shared cluster components.
- Generate gossip and TLS keys.
- Deploy the consensus network and, if enabled, the block node (in parallel).
- Set up and start consensus nodes.
- Optionally, deploy mirror node, explorer, and relay in parallel for faster startup.
- Create predefined test accounts.
- Write deployment notes, versions, port-forward details, and account data to a local output directory.
The difference is that Falcon reads a YAML file and maps its top-level sections to the underlying Solo subcommands.
| Values file section | Solo subcommand invoked |
|---|---|
network | solo consensus network deploy |
setup | solo consensus node setup |
consensusNode | solo consensus node start |
mirrorNode | solo mirror node add |
explorerNode | solo explorer node add |
relayNode | solo relay node add |
blockNode | solo block node add (when ONE_SHOT_WITH_BLOCK_NODE=true) |
For the full list of supported CLI flags per section, see the
Falcon Values File Reference.
If you set network.--application-properties, see
Custom Application Properties
for the difference between Solo’s default merge mode and full overwrite mode.
Prepare a Falcon values file
Instead of authoring a values file by hand, you can use the interactive prepare wizard to generate one:
solo one-shot falcon prepare
The wizard prompts for component toggles (mirror node, explorer, relay), consensus node count, component versions, ingress, storage type, developer options, and port forwarding. All prompts have sensible defaults, so you can press Enter to accept them.
To generate a values file with all defaults (no prompts):
solo one-shot falcon prepare --quiet-mode
To specify a custom output path:
solo one-shot falcon prepare --output-values-file ./my-values.yaml
Output file location
By default, the generated file is written to ~/.solo/cache/falcon-values.yaml — a deterministic absolute path regardless of how or where Solo is invoked. You can override this with --output-values-file. The success message always prints the fully resolved path so there is no ambiguity.
- Default:
~/.solo/cache/falcon-values.yaml— always the same location. - Relative path:
--output-values-file ./configs/my-values.yaml— resolved against the current working directory (so/tmp/configs/my-values.yamlif invoked from/tmp). - Absolute path:
--output-values-file /tmp/falcon-values.yaml— written to that exact location regardless of the current working directory.
The generated file is ready to use with solo one-shot falcon deploy --values-file. For the full list of flags the wizard sets, see the Falcon Values File Reference.
Create a Falcon Values File
Create a YAML file to control every component of your Solo deployment. The file can have any name -falcon-values.yaml is used throughout this guide as a convention.
Note: Keys within each section must be the full CLI flag name including the
--prefix - for example,--consensus-node-version, notconsensus-node-versionor-r. Any section you omit from the file is skipped, and Solo uses the built-in defaults for that component.
Example: Single-Node Falcon Deployment
The following falcon-values.yaml example deploys a standard single-node network with mirror node,
explorer, and relay enabled:
network:
--consensus-node-version: "v0.71.0"
--pvcs: false
setup:
--consensus-node-version: "v0.71.0"
consensusNode:
--force-port-forward: true
mirrorNode:
--enable-ingress: true
--pinger: true
--force-port-forward: true
explorerNode:
--enable-ingress: true
--force-port-forward: true
relayNode:
--node-aliases: "node1"
--force-port-forward: true
Deploy with Falcon one-shot
Run Falcon deployment by pointing Solo at the values file:
solo one-shot falcon deploy --values-file falcon-values.yaml
Solo creates a one-shot deployment, applies the values from the YAML file to the appropriate subcommands, and then deploys the full environment.
Command-Line Flags (Not in YAML File)
The following flags are passed on the command line and cannot be set in the YAML file:
--deployment,--namespace,--cluster-ref,--num-consensus-nodes
Note: --values-file specifies which YAML file to load.
--values-fileselects the YAML file to load.--deployment,--namespace,--cluster-ref, and--num-consensus-nodesare top-level one-shot inputs.
Important: Do not rely on
--deploymentinsidefalcon-values.yaml. Solo intentionally ignores--deploymentvalues from section content during Falcon argument expansion. Set the deployment name on the command line if you need a specific name.
Tip: When not specified, Falcon uses these defaults:
--deployment one-shot,--namespace one-shot,--cluster-ref one-shot, and--num-consensus-nodes 1. Pass any of these explicitly on the command line to override them.
Example:
solo one-shot falcon deploy \
--deployment falcon-demo \
--cluster-ref one-shot \
--values-file falcon-values.yaml
Multi-Node Falcon Deployment
For multiple consensus nodes, set the node count on the Falcon command and then provide matching per-node settings where required.
Example:
solo one-shot falcon deploy \ --deployment falcon-multi \ --num-consensus-nodes 3 \ --values-file falcon-values.yamlExample multi-node values file:
network: --consensus-node-version: "v0.71.0" --pvcs: true setup: --consensus-node-version: "v0.71.0" consensusNode: --force-port-forward: true --stake-amounts: "100,100,100" mirrorNode: --enable-ingress: true --pinger: true explorerNode: --enable-ingress: true relayNode: --node-aliases: "node1,node2,node3"The
--node-aliasesvalue in therelayNodesection must match the node aliases generated by--num-consensus-nodes. Nodes are auto-namednode1,node2,node3, and so on. Setting this to onlynode1is valid if you want the relay to serve a single node, but specifying all aliases is typical for full coverage.Use this pattern when you need a repeatable multi-node deployment but do not want to manage each step manually.
Note: Multi-node deployments require more host resources than single-node deployments. Follow the resource guidance in System Readiness, and increase Docker memory and CPU allocation before deploying.
Common Falcon Customisations
Because each YAML section maps directly to the corresponding Solo subcommand, you can use Falcon to centralise advanced options such as:
- Custom release tags for the consensus node platform.
- Local chart directories for mirror node, relay, explorer, or block node.
- Local consensus node build paths for development workflows.
- Ingress and domain settings.
- Mirror node external database settings.
- Node startup settings such as state files, port forwarding, and stake amounts.
- Storage backends and credentials for stream file handling.
Example: Local Development with Local Chart Directories
setup:
--local-build-path: "/path/to/hiero-consensus-node/hedera-node/data"
mirrorNode:
--mirror-node-chart-dir: "/path/to/hiero-mirror-node/charts"
relayNode:
--relay-chart-dir: "/path/to/hiero-json-rpc-relay/charts"
explorerNode:
--explorer-chart-dir: "/path/to/hiero-mirror-node-explorer/charts"
This pattern is useful for local integration testing against unpublished component builds.
Falcon with Block Node
Falcon can also include block node configuration.
Note: Block node workflows are advanced and require higher resource allocation and version compatibility across consensus node, block node, and related components. Docker memory must be set to at least 16 GB before deploying with block node enabled.
Block node support also requires the
ONE_SHOT_WITH_BLOCK_NODE=trueenvironment variable to be set before runningfalcon deploy. Without it, Solo skips the block node add step even if ablockNodesection is present in the values file.
Block node deployment is subject to version compatibility requirements. Minimum versions are consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Mixing incompatible versions will cause the deployment to fail. Check the Version Compatibility Reference before enabling block node.
Example:
network:
--consensus-node-version: "v0.72.0"
setup:
--consensus-node-version: "v0.72.0"
consensusNode:
--force-port-forward: true
blockNode:
--block-node-version: "v0.29.0"
--enable-ingress: false
mirrorNode:
--enable-ingress: true
--pinger: true
explorerNode:
--enable-ingress: true
relayNode:
--node-aliases: "node1"
--force-port-forward: true
Use block node settings only when your target Solo and component versions are known to be compatible.
Deployment Output
After a successful Falcon deployment, Solo writes deployment metadata to
~/.solo/one-shot-<deployment>/ where <deployment> is the value of the
--deployment flag (default: one-shot).
This directory typically contains:
notes- human-readable deployment summaryversions- component versions recorded at deploy timeforwards- port-forward configurationaccounts.json- predefined test account keys and IDs. All accounts are ECDSA Alias accounts (EVM-compatible) and include apublicAddressfield. The file also includes the system operator account.
This makes Falcon especially useful for automation, because the deployment artifacts are written to a predictable path after each run.
To inspect deployment output, check the ~/.solo/one-shot-<deployment>/ directory directly.
If port-forwards are interrupted after deployment, restore them by rerunning the component commands (such as solo consensus node start, solo mirror node add, etc.)
Destroy a Falcon Deployment
Destroy the Falcon deployment with:
solo one-shot falcon destroySolo removes deployed extensions first, then destroys the mirror node, network, cluster references, and local deployment metadata.
If multiple deployments exist locally, Solo prompts you to choose which one to destroy unless you pass
--deploymentexplicitly.solo one-shot falcon destroy --deployment falcon-demo
When to Use Falcon vs. Manual Deployment
Use Falcon deployment when you want a single, repeatable command backed by a versioned YAML file.
Use Step-by-Step Manual Deployment when you need to pause between steps, inspect intermediate state, or debug a specific deployment phase in isolation.
In practice:
- Falcon is better for automation and repeatability.
- Manual deployment is better for debugging and low-level control.
Reference
- Falcon Values File Reference - full list of supported CLI flags, types, and defaults for every section.
- Upstream example values file - working reference from the Solo repository.
Tip: If you are creating a values file for the first time, start from the annotated template in the Solo repository rather than writing one from scratch:
examples/one-shot-falcon/falcon-values.yamlThis file includes all supported sections and flags with inline comments explaining each option. Copy it, remove what you do not need, and adjust the values for your environment.
2.2.2 - Falcon Values File Reference
Overview
This page catalogs the Solo CLI flags accepted under each top-level section of a Falcon values file. Each entry corresponds to the command-line flag that the underlying Solo subcommand accepts.
Sections map to subcommands as follows:
| Section | Solo subcommand |
|---|---|
network | solo consensus network deploy |
setup | solo consensus node setup |
consensusNode | solo consensus node start |
mirrorNode | solo mirror node add |
explorerNode | solo explorer node add |
relayNode | solo relay node add |
blockNode | solo block node add |
All flag names must be written in long form with double dashes (for example,
--consensus-node-version). Flags left empty ("") or matching their default value are
ignored by Solo at argument expansion time.
Note: Not every flag listed here is relevant to every deployment. Use this page as a lookup when writing or debugging a values file. For a working example file, see the upstream reference at https://github.com/hiero-ledger/solo/tree/main/examples/one-shot-falcon.
Consensus Network Deploy — network
Flags passed to solo consensus network deploy.
| Flag | Type | Default | Description |
|---|---|---|---|
--consensus-node-version | string | current Hedera platform version | Consensus node version to deploy (e.g. v0.71.0). |
--pvcs | boolean | false | Enable Persistent Volume Claims for consensus node storage. Required for node add operations. |
--load-balancer | boolean | false | Enable load balancer for network node proxies. |
--chart-dir | string | — | Path to a local Helm chart directory for the Solo network chart. |
--solo-chart-version | string | current chart version | Specific Solo testing chart version to deploy. |
--haproxy-ips | string | — | Static IP mapping for HAProxy pods (e.g. node1=127.0.0.1,node2=127.0.0.2). |
--envoy-ips | string | — | Static IP mapping for Envoy proxy pods. |
--debug-node-alias | string | — | Enable the default JVM debug port (5005) for the specified node alias. |
--domain-names | string | — | Custom domain name mapping per node alias (e.g. node1=node1.example.com). |
--grpc-tls-cert | string | — | TLS certificate path for gRPC, per node alias (e.g. node1=/path/to/cert). |
--grpc-web-tls-cert | string | — | TLS certificate path for gRPC Web, per node alias. |
--grpc-tls-key | string | — | TLS certificate key path for gRPC, per node alias. |
--grpc-web-tls-key | string | — | TLS certificate key path for gRPC Web, per node alias. |
--storage-type | string | minio_only | Stream file storage backend. Options: minio_only, aws_only, gcs_only, aws_and_gcs. |
--gcs-write-access-key | string | — | GCS write access key. |
--gcs-write-secrets | string | — | GCS write secret key. |
--gcs-endpoint | string | — | GCS storage endpoint URL. |
--gcs-bucket | string | — | GCS bucket name. |
--gcs-bucket-prefix | string | — | GCS bucket path prefix. |
--aws-write-access-key | string | — | AWS write access key. |
--aws-write-secrets | string | — | AWS write secret key. |
--aws-endpoint | string | — | AWS storage endpoint URL. |
--aws-bucket | string | — | AWS bucket name. |
--aws-bucket-region | string | — | AWS bucket region. |
--aws-bucket-prefix | string | — | AWS bucket path prefix. |
--settings-txt | string | template | Path to a custom settings.txt file for consensus nodes. |
--application-properties | string | template | Path to a custom application.properties file. Defaults to key-level merge mode; add # SOLO_ENABLE_OVERWRITE=true to the file for overwrite mode. See Custom Application Properties. |
--application-env | string | template | Path to a custom application.env file. |
--api-permission-properties | string | template | Path to a custom api-permission.properties file. |
--bootstrap-properties | string | template | Path to a custom bootstrap.properties file. |
--log4j2-xml | string | template | Path to a custom log4j2.xml file. |
--genesis-throttles-file | string | — | Path to a custom throttles.json file for network genesis. |
--service-monitor | boolean | false | Install a ServiceMonitor custom resource for Prometheus metrics. |
--pod-log | boolean | false | Install a PodLog custom resource for node pod log monitoring. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--values-file | string | — | Comma-separated Helm chart values file paths (not the Falcon values file). |
Consensus Node Setup — setup
Flags passed to solo consensus node setup.
| Flag | Type | Default | Description |
|---|---|---|---|
--consensus-node-version | string | current Hedera platform version | Consensus node version to set up. Must match network.--consensus-node-version. |
--local-build-path | string | — | Path to a local Hiero consensus node build (e.g. ~/hiero-consensus-node/hedera-node/data). Used for local development workflows. |
--app | string | HederaNode.jar | Name of the consensus node application binary. |
--app-config | string | — | Path to a JSON configuration file for the testing app. |
--admin-public-keys | string | — | Comma-separated DER-encoded ED25519 public keys in node alias order. |
--domain-names | string | — | Custom domain name mapping per node alias. |
--debug | boolean | false | Enable debug mode. (Formerly --dev, which is deprecated — see note below.) |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--cache-dir | string | ~/.solo/cache | Local cache directory for downloaded artifacts. |
Deprecated: The
--devflag has been renamed to--debug.--devstill works as an alias but is deprecated and prints a warning. The--devalias will no longer be supported once Solo0.82.0reaches its end of support date.
Consensus Node Start — consensusNode
Flags passed to solo consensus node start.
| Flag | Type | Default | Description |
|---|---|---|---|
--force-port-forward | boolean | true | Force port forwarding to access network services locally. |
--stake-amounts | string | — | Comma-separated stake amounts in node alias order (e.g. 100,100,100). Required for multi-node deployments that need non-default stakes. |
--state-file | string | — | Path to a zipped state file to restore the network from. |
--debug-node-alias | string | — | Enable JVM debug port (5005) for the specified node alias. |
--app | string | HederaNode.jar | Name of the consensus node application binary. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
Mirror Node Add — mirrorNode
Flags passed to solo mirror node add.
| Flag | Type | Default | Description |
|---|---|---|---|
--mirror-node-version | string | current version | Mirror node Helm chart version to deploy. |
--enable-ingress | boolean | false | Deploy an ingress controller for the mirror node. |
--force-port-forward | boolean | true | Enable port forwarding for mirror node services. |
--pinger | boolean | false | Enable the mirror node Pinger service. |
--mirror-static-ip | string | — | Static IP address for the mirror node load balancer. |
--domain-name | string | — | Custom domain name for the mirror node. |
--ingress-controller-value-file | string | — | Path to a Helm values file for the ingress controller. |
--mirror-node-chart-dir | string | — | Path to a local mirror node Helm chart directory. |
--use-external-database | boolean | false | Connect to an external PostgreSQL database instead of the chart-bundled one. |
--external-database-host | string | — | Hostname of the external database. Requires --use-external-database. |
--external-database-owner-username | string | — | Owner username for the external database. |
--external-database-owner-password | string | — | Owner password for the external database. |
--external-database-read-username | string | — | Read-only username for the external database. |
--external-database-read-password | string | — | Read-only password for the external database. |
--storage-type | string | minio_only | Stream file storage backend for the mirror node importer. |
--storage-read-access-key | string | — | Storage read access key for the mirror node importer. |
--storage-read-secrets | string | — | Storage read secret key for the mirror node importer. |
--storage-endpoint | string | — | Storage endpoint URL for the mirror node importer. |
--storage-bucket | string | — | Storage bucket name for the mirror node importer. |
--storage-bucket-prefix | string | — | Storage bucket path prefix. |
--storage-bucket-region | string | — | Storage bucket region. |
--operator-id | string | — | Operator account ID for the mirror node. |
--operator-key | string | — | Operator private key for the mirror node. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--values-file | string | — | Comma-separated Helm chart values file paths for the mirror node chart. |
Explorer Add — explorerNode
Flags passed to solo explorer node add.
| Flag | Type | Default | Description |
|---|---|---|---|
--explorer-version | string | current version | Hiero Explorer Helm chart version to deploy. |
--enable-ingress | boolean | false | Deploy an ingress controller for the explorer. |
--force-port-forward | boolean | true | Enable port forwarding for the explorer service. |
--domain-name | string | — | Custom domain name for the explorer. |
--ingress-controller-value-file | string | — | Path to a Helm values file for the ingress controller. |
--explorer-chart-dir | string | — | Path to a local Hiero Explorer Helm chart directory. |
--explorer-static-ip | string | — | Static IP address for the explorer load balancer. |
--enable-explorer-tls | boolean | false | Enable TLS for the explorer. Requires cert-manager. |
--explorer-tls-host-name | string | explorer.solo.local | Hostname used for the explorer TLS certificate. |
--tls-cluster-issuer-type | string | self-signed | TLS cluster issuer type. Options: self-signed, acme-staging, acme-prod. |
--mirror-node-id | number | — | ID of the mirror node instance to connect the explorer to. |
--mirror-namespace | string | — | Kubernetes namespace of the mirror node. |
--solo-chart-version | string | current version | Solo chart version used for explorer cluster setup. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--values-file | string | — | Comma-separated Helm chart values file paths for the explorer chart. |
JSON-RPC Relay Add — relayNode
Flags passed to solo relay node add.
| Flag | Type | Default | Description |
|---|---|---|---|
--relay-version | string | current version | Hiero JSON-RPC Relay version to deploy. |
--node-aliases | string | — | Comma-separated node aliases the relay will observe (e.g. node1 or node1,node2). |
--replica-count | number | 1 | Number of relay replicas to deploy. |
--chain-id | string | 298 | EVM chain ID exposed by the relay (Hedera testnet default). |
--force-port-forward | boolean | true | Enable port forwarding for the relay service. |
--domain-name | string | — | Custom domain name for the relay. |
--relay-chart-dir | string | — | Path to a local Hiero JSON-RPC Relay Helm chart directory. |
--operator-id | string | — | Operator account ID for relay transaction signing. |
--operator-key | string | — | Operator private key for relay transaction signing. |
--mirror-node-id | number | — | ID of the mirror node instance the relay will query. |
--mirror-namespace | string | — | Kubernetes namespace of the mirror node. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--values-file | string | — | Comma-separated Helm chart values file paths for the relay chart. |
Block Node Add — blockNode
Flags passed to solo block node add.
Important: The
blockNodesection is only read whenONE_SHOT_WITH_BLOCK_NODE=trueis set in the environment. Otherwise Solo skips the block node add step regardless of whether ablockNodesection is present. Version requirements: Consensus node ≥ v0.72.0 and block node ≥ 0.29.0. Use--forceto bypass version gating during testing.
| Flag | Type | Default | Description |
|---|---|---|---|
--block-node-version | string | current version | Hiero block node version to deploy. |
--consensus-node-version | string | current Hedera platform version | Version of the consensus node the block node will serve. Used for the version compatibility check. |
--component-image | string | — | Block node image override: a registry reference (e.g. ghcr.io/<org>/<image>:<tag>), a locally built image, or a Kind-attached local registry image. |
--enable-ingress | boolean | false | Deploy an ingress controller for the block node. |
--domain-name | string | — | Custom domain name for the block node. |
--debug | boolean | false | Enable debug mode for the block node. (Formerly --dev, which is deprecated — see note below.) |
--block-node-chart-dir | string | — | Path to a local Hiero block node Helm chart directory. |
--quiet-mode | boolean | false | Suppress confirmation prompts. |
--values-file | string | — | Comma-separated Helm chart values file paths for the block node chart. |
Deprecated: The
--devflag has been renamed to--debug.--devstill works as an alias but is deprecated and prints a warning. The--devalias will no longer be supported once Solo0.82.0reaches its end of support date.
Top-Level Falcon Command Flags
The following flags are passed directly on the solo one-shot falcon deploy command
line. They are not read from the values file sections.
| Flag | Type | Default | Description |
|---|---|---|---|
--values-file | string | — | Path to the Falcon values YAML file. |
--deployment | string | one-shot | Deployment name for Solo’s internal state. |
--namespace | string | one-shot | Kubernetes namespace to deploy into. |
--cluster-ref | string | one-shot | Cluster reference name. |
--num-consensus-nodes | number | 1 | Number of consensus nodes to deploy. |
--parallel-deploy | boolean | true | Run independent deploy stages in parallel (consensus+block, mirror+accounts, explorer+relay). Use --no-parallel-deploy for sequential execution. |
--quiet-mode | boolean | false | Suppress all interactive prompts. |
--force | boolean | false | Force actions that would otherwise be skipped. |
Falcon Prepare — prepare
Flags accepted by solo one-shot falcon prepare, the interactive wizard that generates a Falcon values file. The wizard prompts for nearly every values-file field, but the following CLI flags control its output behavior directly.
| Flag | Type | Default | Description |
|---|---|---|---|
--output-values-file | string | ~/.solo/cache/falcon-values.yaml | Path to the generated values file. Absolute paths are written as-is. Relative paths are resolved against the current working directory. |
--quiet-mode | boolean | false | Generate a values file using all defaults without prompting. |
All other prepare-time flags correspond directly to the per-section values shown in the tables above and are documented under their respective network, setup, consensusNode, mirrorNode, explorerNode, relayNode, and blockNode sections.
2.2.3 - Step-by-Step Manual Deployment
Overview
Manual deployment lets you deploy each Solo network component individually, giving you full control over configuration, sequencing, and troubleshooting. Use this approach when you need to customise specific steps, debug a component in isolation, or integrate Solo into a bespoke automation pipeline.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness — your local environment meets all hardware and software requirements (Docker, kind, kubectl, helm, Solo).
- Quickstart — you have a running Kind cluster.
- Set your environment variables if you have not already done so:
export SOLO_CLUSTER_NAME=solo
export SOLO_NAMESPACE=solo-deployment
export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
export SOLO_DEPLOYMENT=solo-deployment
$env:SOLO_CLUSTER_NAME = 'solo'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster'
$env:SOLO_DEPLOYMENT = 'solo-deployment'
Deployment Steps
Note: The expected output blocks below are fetched from the latest published Solo release at build time and will always reflect the current version.
1. Connect Cluster and Create Deployment
Connect Solo to the Kind cluster and create a new deployment configuration:
# Connect to the Kind cluster solo cluster-ref config connect \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --context kind-${SOLO_CLUSTER_NAME} # Create a new deployment solo deployment config create \ -n "${SOLO_NAMESPACE}" \ --deployment "${SOLO_DEPLOYMENT}"Expected Output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : cluster-ref config connect --cluster-ref kind-solo --context kind-solo ********************************************************************************** *************************************************************************************** Note: solo stores various artifacts (config, logs, keys etc.) in its home directory: /home/runner/.solo If a full reset is needed, delete the directory or relevant sub-directories before running 'solo'. *************************************************************************************** ❯ Initialize ✔ Initialize ❯ Validating cluster ref: ✔ Validating cluster ref: kind-solo ❯ Test connection to cluster: ✔ Test connection to cluster: kind-solo ❯ Associate a context with a cluster reference: ✔ Associate a context with a cluster reference: kind-solo Run 'solo cache image pull' to pre-pull the 21 container images (1.5 GB) Solo deploys.******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : deployment config create --namespace solo --realm 0 --shard 0 Kubernetes Namespace : solo ********************************************************************************** ❯ Initialize ✔ Initialize ❯ Add deployment to local config ✔ Adding deployment: solo-deployment with namespace: solo to local config
2. Add Cluster to Deployment
Attach the cluster to your deployment and specify the number of consensus nodes:
1. Single node:
solo deployment cluster attach \ --deployment "${SOLO_DEPLOYMENT}" \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --num-consensus-nodes 12. Multiple nodes (e.g., –num-consensus-nodes 3):
solo deployment cluster attach \ --deployment "${SOLO_DEPLOYMENT}" \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --num-consensus-nodes 3Expected Output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : deployment cluster attach --cluster-ref kind-solo --num-consensus-nodes 1 ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.7s] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.8s] ✔ Check dependencies [0.8s] ❯ Setup chart manager ✔ Setup chart manager [7s] ❯ Initialize ✔ Initialize ❯ Verify args ✔ Verify args ❯ check ledger phase ✔ check ledger phase ❯ Test cluster reference connection ✔ Test cluster reference connection: kind-solo, context: kind-solo ❯ Verify prerequisites ✔ Verify prerequisites ❯ Check for other deployments ✔ Check for other deployments ❯ add cluster-ref in local config deployments Adding cluster-ref: kind-solo for deployment: solo-deployment in local config ✔ add cluster-ref: kind-solo for deployment: solo-deployment in local config ❯ create remote config for deployment ✔ create remote config for deployment: solo-deployment in cluster reference: kind-solo [0.1s]
3. Generate Keys
Generate the gossip and TLS keys for your consensus nodes:
solo keys consensus generate \ --gossip-keys \ --tls-keys \ --deployment "${SOLO_DEPLOYMENT}"PEM key files are written to
~/.solo/cache/keys/.Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : keys consensus generate --gossip-keys --tls-keys ********************************************************************************** ❯ Initialize ✔ Initialize ❯ Generate gossip keys ❯ Backup old files ✔ Backup old files ❯ Gossip key for node: node1 ✔ Gossip key for node: node1 [0.1s] ✔ Generate gossip keys [0.1s] ❯ Generate gRPC TLS Keys ❯ Backup old files ❯ TLS key for node: node1 ✔ Backup old files ✔ TLS key for node: node1 [0.3s] ✔ Generate gRPC TLS Keys [0.3s] ❯ Finalize ✔ Finalize
4. Set Up Cluster with Shared Components
Install shared cluster-level components (MinIO Operator, Prometheus CRDs, etc.) into the cluster setup namespace:
solo cluster-ref config setup --cluster-setup-namespace "${SOLO_CLUSTER_SETUP_NAMESPACE}"Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : cluster-ref config setup --cluster-setup-namespace solo-cluster ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.6s] ❯ Initialize ✔ Initialize ❯ Install cluster charts ❯ Install pod-monitor-role ClusterRole ✅ ClusterRole pod-monitor-role installed successfully in context kind-solo ✔ Install pod-monitor-role ClusterRole ❯ Install MinIO Operator chart ✅ MinIO Operator chart installed successfully ✔ Install MinIO Operator chart [0.6s] ✔ Install cluster charts [0.7s]
5. Deploy the Network
Deploy the Solo network Helm chart, which provisions the consensus node pods, HAProxy, Envoy, and MinIO:
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}"To provide a custom consensus node
application.propertiesfile, pass--application-properties <path>. Solo merges custom files with its generated defaults unless the file includes the overwrite marker. See Custom Application Properties for merge and overwrite examples.Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : consensus network deploy --consensus-node-version v0.78.1 ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.8s] ❯ Initialize ❯ Acquire lock ✔ Acquire lock - lock acquired successfully, attempt: 1/10 ✔ Initialize [0.3s] ❯ Check for an existing network deployment ✔ Check for an existing network deployment ❯ Copy gRPC TLS Certificates ↓ Copy gRPC TLS Certificates [SKIPPED: Copy gRPC TLS Certificates] ❯ Copy node keys to secrets ❯ Copy TLS keys ❯ Node: node1, cluster: kind-solo ❯ Copy Gossip keys ✔ Copy TLS keys ✔ Copy Gossip keys ✔ Node: node1, cluster: kind-solo ✔ Copy node keys to secrets ❯ Remove cached keys ✔ Remove cached keys ❯ Install monitoring CRDs ❯ Pod Logs CRDs ❯ Prometheus Operator CRDs ✔ Pod Logs CRDs - Installed prometheus-operator-crds chart, version: 24.0.2 ✔ Prometheus Operator CRDs [3s] ✔ Install monitoring CRDs [3s] ❯ Install chart 'solo-deployment' - Installed solo-deployment chart, version: 0.67.0 ✔ Install chart 'solo-deployment' [1s] ❯ Patch ServiceMonitor for Prometheus discovery ✔ Patch ServiceMonitor for Prometheus discovery ❯ Check for load balancer ↓ Check for load balancer [SKIPPED: Check for load balancer] ❯ Redeploy chart with external IP address config ↓ Redeploy chart with external IP address config [SKIPPED: Redeploy chart with external IP address config] ❯ Check node pods are running ❯ Check Node: node1, Cluster: kind-solo ✔ Check Node: node1, Cluster: kind-solo [16s] ✔ Check node pods are running [16s] ❯ Install zip, unzip and curl in the consensus node image ↓ Install zip, unzip and curl in the consensus node image [SKIPPED: Install zip, unzip and curl in the consensus node image] ❯ Verify persistent volume claim mounts ↓ Verify persistent volume claim mounts [SKIPPED: Verify persistent volume claim mounts] ❯ Check proxy pods are running ❯ Check HAProxy for: node1, cluster: kind-solo ❯ Check Envoy Proxy for: node1, cluster: kind-solo ✔ Check HAProxy for: node1, cluster: kind-solo ✔ Check Envoy Proxy for: node1, cluster: kind-solo ✔ Check proxy pods are running ❯ Check auxiliary pods are ready ❯ Check MinIO ↓ Check MinIO [SKIPPED: Check MinIO] ✔ Check auxiliary pods are ready ❯ Add node and proxies to remote config ✔ Add node and proxies to remote config ❯ Copy wraps lib into consensus node ↓ Copy wraps lib into consensus node [SKIPPED: Copy wraps lib into consensus node] ❯ Copy block-nodes.json ✔ Copy block-nodes.json [0.9s] ❯ Copy JFR config file to nodes ↓ Copy JFR config file to nodes [SKIPPED: Copy JFR config file to nodes]
6. Set Up Consensus Nodes
Download the consensus node platform software and configure each node:
export CONSENSUS_NODE_VERSION=v0.66.0 solo consensus node setup \ --deployment "${SOLO_DEPLOYMENT}" \ --consensus-node-version "${CONSENSUS_NODE_VERSION}"On native Windows (PowerShell), set the version with
$env:CONSENSUS_NODE_VERSION = 'v0.66.0'and reference variables as$env:SOLO_DEPLOYMENT/$env:CONSENSUS_NODE_VERSION.Example output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : consensus node setup --consensus-node-version v0.78.1 ********************************************************************************** ❯ Load configuration ✔ Load configuration [0.1s] ❯ Initialize ✔ Initialize [0.1s] ❯ Validate nodes states ❯ Validating state for node node1 ✔ Validating state for node node1 - valid state: requested ✔ Validate nodes states ❯ Identify network pods ❯ Check network pod: node1 ✔ Check network pod: node1 ✔ Identify network pods ❯ Fetch platform software into network nodes ❯ Update node: node1 [ platformVersion = v0.78.1, context = kind-solo ] ✔ Update node: node1 [ platformVersion = v0.78.1, context = kind-solo ] [6s] ✔ Fetch platform software into network nodes [8s] ❯ Setup network nodes ❯ Node: node1 ❯ Copy configuration files ✔ Copy configuration files [0.5s] ❯ Set file permissions ✔ Set file permissions [0.4s] ✔ Node: node1 [1s] ✔ Setup network nodes [1s] ❯ Update block-nodes.json ✔ Update block-nodes.json [0.9s] ❯ setup network node folders ✔ setup network node folders [0.1s] ❯ Change node state to configured in remote config ✔ Change node state to configured in remote config
7. Start Consensus Nodes
Start all configured nodes and wait for them to reach ACTIVE status:
solo consensus node start --deployment "${SOLO_DEPLOYMENT}"Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : consensus node start ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.6s] ❯ Load configuration ✔ Load configuration [0.1s] ❯ Initialize ✔ Initialize ❯ Validate nodes states ❯ Validating state for node node1 ✔ Validating state for node node1 - valid state: configured ✔ Validate nodes states ❯ Identify existing network nodes ❯ Check network pod: node1 ✔ Check network pod: node1 ✔ Identify existing network nodes ❯ Upload state files network nodes ↓ Upload state files network nodes [SKIPPED: Upload state files network nodes] ❯ Install override-network.json ↓ Install override-network.json [SKIPPED: Install override-network.json] ❯ Starting nodes ❯ Start node: node1 ✔ Start node: node1 [1s] ✔ Starting nodes [1s] ❯ Enable port forwarding for JVM debugger ↓ Enable port forwarding for JVM debugger [SKIPPED: Enable port forwarding for JVM debugger] ❯ Check all nodes are ACTIVE or FREEZE_COMPLETE ↓ Check all nodes are ACTIVE or FREEZE_COMPLETE [SKIPPED: No state file supplied] ❯ Check node proxies are ACTIVE ↓ Check node proxies are ACTIVE [SKIPPED: Nodes did not come up frozen] ❯ Change node state to frozen in remote config ↓ Change node state to frozen in remote config [SKIPPED: Nodes did not come up frozen] ❯ Check nodes are ACTIVE and proxies are ready ❯ Check all nodes are ACTIVE ❯ Check node proxies are ACTIVE ❯ Check proxy for node: node1 ❯ Check network pod: node1 ✔ Check proxy for node: node1 ✔ Check node proxies are ACTIVE Using requested port 30212 Stopping port-forward for port [30212] Using requested port 30212 Stopping port-forward for port [30212] Using requested port 30212 ✔ Check network pod: node1 - gRPC readiness 3/3, attempt: 2/20 [39s] ✔ Check all nodes are ACTIVE [39s] ✔ Check nodes are ACTIVE and proxies are ready [39s] ❯ Enable port forwarding for debug port and/or GRPC port Using requested port 35211 ✔ Enable port forwarding for debug port and/or GRPC port ❯ Emit node started event ✔ Emit node started event ❯ Wait for TSS ❯ Waiting for node: node1 ✔ Waiting for node: node1, attempt 1/60 [10s] ✔ Wait for TSS [10s] ❯ set gRPC Web endpoint Stopping port-forward for port [30212] Using requested port 30212 ✔ set gRPC Web endpoint [3s] ❯ Change node state to started in remote config ✔ Change node state to started in remote config ❯ Add node stakes ❯ Adding stake for node: node1 ✔ Adding stake for node: node1 [2s] ✔ Add node stakes [2s] Stopping port-forward for port [30212]
8. Deploy Mirror Node
Deploy the Hedera Mirror Node, which indexes all transaction data and exposes a REST API and gRPC endpoint:
solo mirror node add \ --deployment "${SOLO_DEPLOYMENT}" \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --enable-ingress \ --pinger \ --force-port-forwardThe
--pingerflag keeps the mirror node’s importer active by regularly submitting record files. The--enable-ingressflag installs the HAProxy ingress controller for the mirror node REST API.Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : mirror node add --cluster-ref kind-solo --enable-ingress --quiet-mode ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.6s] ❯ Initialize ❯ Acquire lock ✔ Acquire lock - lock acquired successfully, attempt: 1/10 ✔ Initialize [0.3s] ❯ Add mirror node to remote config ✔ Add mirror node to remote config ❯ load node client Using requested port 30212 ✔ load node client [1s] ❯ Deploy charts ❯ Ensure mirror-node uploader secret ↓ Ensure mirror-node uploader secret [SKIPPED: Ensure mirror-node uploader secret] ❯ Enable shared resources ❯ Install Shared Resources chart ✔ Install Shared Resources chart [1s] ❯ Load redis credentials ✔ Load redis credentials ❯ Initialize Postgres pod ❯ Wait for Postgres pod to be ready ✔ Wait for Postgres pod to be ready [10s] ✔ Initialize Postgres pod [10s] ❯ Add shared resource components to remote config ✔ Add shared resource components to remote config ✔ Enable shared resources [11s] ❯ Prime mirror-node postgres secret ✔ Prime mirror-node postgres secret [0.8s] ❯ Delete stale mirror redis secret ✔ Delete stale mirror redis secret ❯ Run database initialization script ✔ Run database initialization script [2s] ❯ Enable mirror-node ❯ Prepare address book ✔ Prepare address book ❯ Install mirror ingress controller - Installed haproxy-ingress-1 chart, version: 0.14.5 ✔ Install mirror ingress controller [0.5s] ❯ Deploy mirror-node - Installed mirror chart, version: v0.164.2 ✔ Deploy mirror-node [1s] ❯ Wait for mirror node database schema ✔ Wait for mirror node database schema [20s] ❯ Grant readonly role to mirror_rest on external database ↓ Grant readonly role to mirror_rest on external database [SKIPPED: Grant readonly role to mirror_rest on external database] ✔ Enable mirror-node [21s] ✔ Deploy charts [36s] ❯ Check pods are ready ❯ Check Grpc ❯ Check Importer ❯ Check Rest ❯ Check Rest Java ❯ Check Web3 ✔ Check Grpc ✔ Check Rest Java ✔ Check Rest ✔ Check Web3 ✔ Check Importer ✔ Check pods are ready [0.1s] ❯ Enable port forwarding for mirror ingress controller Using requested port 38081 ✔ Enable port forwarding for mirror ingress controller ❯ Enable port forwarding for mirror node JVM debugger ↓ Enable port forwarding for mirror node JVM debugger [SKIPPED: Enable port forwarding for mirror node JVM debugger] ❯ Show user messages *** Port forwarding enabled: *** ------------------------------------------------------------------------------- - Mirror ingress controller port forward enabled on 127.0.0.1:38081 ------------------------------------------------------------------------------- ✔ Show user messages Stopping port-forward for port [30212]
9. Deploy Explorer
Deploy the Hiero Explorer, a web UI for browsing transactions and accounts:
solo explorer node add \ --deployment "${SOLO_DEPLOYMENT}" \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --force-port-forwardExpected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : explorer node add --cluster-ref kind-solo --quiet-mode ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.7s] ❯ Initialize ❯ Acquire lock ✔ Acquire lock - lock acquired successfully, attempt: 1/10 ✔ Initialize [0.4s] ❯ Load remote config ✔ Load remote config [0.1s] ❯ Add explorer to remote config ✔ Add explorer to remote config ❯ Install cert manager ↓ Install cert manager [SKIPPED: Install cert manager] ❯ Install explorer - Installed hiero-explorer-1 chart, version: 26.2.0 ✔ Install explorer [0.4s] ❯ Install explorer ingress controller ↓ Install explorer ingress controller [SKIPPED: Install explorer ingress controller] ❯ Check explorer pod is ready ✔ Check explorer pod is ready [4s] ❯ Check haproxy ingress controller pod is ready ↓ Check haproxy ingress controller pod is ready [SKIPPED: Check haproxy ingress controller pod is ready] ❯ Check load balancer is assigned ↓ Check load balancer is assigned [SKIPPED: Check load balancer is assigned] ❯ Enable port forwarding for explorer No port forward config found for Explorer Using requested port 38080 ✔ Enable port forwarding for explorer ❯ Show user messages *** Port forwarding enabled: *** ------------------------------------------------------------------------------- - Explorer port forward enabled on 127.0.0.1:38080 ------------------------------------------------------------------------------- ✔ Show user messages
10. Deploy JSON-RPC Relay
Deploy the Hiero JSON-RPC Relay to expose an Ethereum-compatible JSON-RPC endpoint for EVM tooling (MetaMask, Hardhat, Foundry, etc.).
The
-iflag (short for--node-aliases) specifies which consensus nodes the relay serves. Pass a comma-separated list for multi-node deployments. Omitting the flag covers all nodes.1. Single node:
solo relay node add \ -i node1 \ --deployment "${SOLO_DEPLOYMENT}"2. Multiple nodes (e.g., 3 nodes):
solo relay node add \ --node-aliases node1,node2,node3 \ --deployment "${SOLO_DEPLOYMENT}"Expected output:
******************************* Solo ********************************************* Version : 0.97.0 Kubernetes Context : kind-solo Kubernetes Cluster : kind-solo Current Command : relay node add --node-aliases node1 --cluster-ref kind-solo --relay-version 0.81.0 ********************************************************************************** ❯ Pre-flight: check Docker Desktop containerd setting ✔ Pre-flight: check Docker Desktop containerd setting ❯ Check dependencies ❯ Check dependency: helm [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kind [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ❯ Check dependency: kubectl [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kind v0.29.0 (/home/runner/.solo/bin/kind) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] ✔ Check dependency: kubectl v1.32.2 (/home/runner/.solo/bin/kubectl) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependency: helm vv4.3.1 (/home/runner/_work/_tool/helm/4.3.1/x64/linux-amd64/helm) [OS: linux, Release: 6.8.0-149-generic, Arch: x64] [0.1s] ✔ Check dependencies [0.1s] ❯ Setup chart manager ✔ Setup chart manager [0.6s] ❯ Initialize ❯ Acquire lock ✔ Acquire lock - lock acquired successfully, attempt: 1/10 ✔ Initialize [0.3s] ❯ Add relay component in remote config ✔ Add relay component in remote config ❯ Check chart is installed ✔ Check chart is installed [0.1s] ❯ Create relay operator credentials secret ✔ Create relay operator credentials secret ❯ Prepare chart values ✔ Prepare chart values ❯ Deploy JSON RPC Relay - Installed relay-1 chart, version: 0.81.0 ✔ Deploy JSON RPC Relay [0.3s] ❯ Check relay is running ✔ Check relay is running [4s] ❯ Check relay is ready ✔ Check relay is ready [3s] ❯ Check load balancer is assigned ↓ Check load balancer is assigned [SKIPPED: Check load balancer is assigned] ❯ Enable port forwarding for relay node No port forward config found for JSON RPC Relay Using requested port 37546 ✔ Enable port forwarding for relay node ❯ Show user messages *** Port forwarding enabled: *** ------------------------------------------------------------------------------- - JSON RPC Relay port forward enabled on 127.0.0.1:37546 ------------------------------------------------------------------------------- ✔ Show user messages
Cleanup
When you are done, destroy components in the reverse order of deployment.
Important: Always destroy components before destroying the network. Skipping this order can leave orphaned Helm releases and PVCs in your cluster.
1. Destroy JSON-RPC Relay
Pass the same node aliases you used when deploying the relay. For a multi-node deployment, use --node-aliases node1,node2,node3 (or omit the flag to destroy all).
solo relay node destroy \
-i node1 \
--deployment "${SOLO_DEPLOYMENT}" \
--cluster-ref kind-${SOLO_CLUSTER_NAME}
2. Destroy Explorer
solo explorer node destroy \
--deployment "${SOLO_DEPLOYMENT}" \
--force
3. Destroy Mirror Node
solo mirror node destroy \
--deployment "${SOLO_DEPLOYMENT}" \
--force
4. Destroy the Network
solo consensus network destroy \
--deployment "${SOLO_DEPLOYMENT}" \
--force
2.2.4 - Custom Application Properties
Overview
Solo lets you provide a custom application.properties file for consensus nodes
with the --application-properties flag. By default, Solo merges your file with
its generated defaults. If you need complete control over the final file, add an
overwrite marker to your custom file.
Use the default merge mode when you only need to change or add a few properties.
Use overwrite mode only when you want your file to replace Solo’s generated
application.properties content.
Default merge mode
Pass your file to solo consensus network deploy:
solo consensus network deploy \
--deployment "${SOLO_DEPLOYMENT}" \
--application-properties ./config/application.properties
In merge mode, Solo starts with its generated application.properties, then
applies your file as key-level overrides:
- If your file contains a key that already exists in Solo’s generated file, Solo replaces that key’s value.
- If your file contains a new key, Solo appends it to the final file.
- Blank lines and comments in your file are ignored during the merge.
- Solo-generated keys that you do not mention remain in the final file.
Example custom file for merge mode:
# Override only the properties that need to change.
contracts.chainId=298
hedera.recordStream.logPeriod=1
This is the recommended mode for most deployments because Solo keeps its generated defaults while still applying your overrides.
Overwrite mode
To replace Solo’s generated application.properties file, add the overwrite
marker as a comment in your custom file:
# SOLO_ENABLE_OVERWRITE=true
contracts.chainId=298
hedera.recordStream.logPeriod=1
# Include every other property your consensus nodes require.
Then deploy with the same flag:
solo consensus network deploy \
--deployment "${SOLO_DEPLOYMENT}" \
--application-properties ./config/application.properties
The marker must be on a comment line that starts with #. Solo looks for the
exact text SOLO_ENABLE_OVERWRITE=true inside a comment. If the marker is
missing, or if it is written as a normal property instead of a comment, Solo
uses default merge mode.
In overwrite mode, your file becomes the full application.properties content.
Solo does not carry over defaults that are missing from your file, so include
all properties required by the consensus node version and deployment topology
you are running.
Falcon values file
For One-shot Falcon deployments, put the same flag under the network section:
network:
--application-properties: "./config/application.properties"
The merge or overwrite behavior is still controlled by the contents of the
referenced application.properties file. Add # SOLO_ENABLE_OVERWRITE=true to
that file only when you want overwrite mode.
For the complete list of Falcon network flags, see the Falcon Values File Reference.
2.2.5 - Dynamically add, update, and remove Consensus Nodes
Overview
This guide covers how to dynamically manage consensus nodes in a running Solo network - adding new nodes, updating existing ones, and removing nodes that are no longer needed. All three operations can be performed without taking the network offline.
Prerequisites
Before proceeding, ensure you have:
A running Solo network. If you don’t have one, deploy using one of the following methods:
- Quickstart - single command deployment using
solo one-shot single deploy. - Manual Deployment - step-by-step deployment with full control over each component.
- Quickstart - single command deployment using
Set the required environment variables as described below:
export SOLO_CLUSTER_NAME=solo
export SOLO_NAMESPACE=solo-deployment
export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster
export SOLO_DEPLOYMENT=solo-deployment
$env:SOLO_CLUSTER_NAME = 'solo'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster'
$env:SOLO_DEPLOYMENT = 'solo-deployment'
Key and Storage Concepts
Before running any node operation, it helps to understand two concepts that
appear in the prepare step.
Cryptographic Keys
Solo generates two types of keys for each consensus node:
- Gossip keys — used for encrypted node-to-node communication within the
network. Stored as
s-private-node*.pemands-public-node*.pemunder~/.solo/cache/keys/. - TLS keys — used to secure gRPC connections to the node. Stored as
hedera-node*.crtandhedera-node*.keyunder~/.solo/cache/keys/.
When adding a new node, Solo generates a fresh key pair and stores it alongside the keys for existing nodes in the same directory. For more detail, see Where are my keys stored?.
- Gossip keys — used for encrypted node-to-node communication within the
network. Stored as
Persistent Volume Claims (PVCs)
By default, consensus node storage is ephemeral - data stored by a node is lost if its pod crashes or is restarted. This is intentional for lightweight local testing where persistence is not required.
The
--pvcs trueflag creates Persistent Volume Claims (PVCs) for the node, ensuring its state survives pod restarts. Enable this flag for any node that needs to persist across restarts or that will participate in longer-running test scenarios.Note: PVCs are not enabled by default. Enable them only if your node needs to persist state across pod restarts.
Staging Directory
The
--output-dir contextflag specifies a local staging directory where Solo writes all artifacts produced duringprepare. Solo’s working files are stored under~/.solo/— if you use a relative path likecontext, the directory is created in your current working directory. Do not delete it untilexecutehas completed successfully.
Adding a Node to an Existing Network
You can dynamically add a new consensus node to a running network without taking the network offline. This process involves three stages: preparing the node’s keys and configuration, submitting the on-chain transaction, and executing the addition.
Step 1: Prepare the new node
Generate the new node’s gossip and TLS keys, create its persistent volumes, and stage its configuration into an output directory:
solo consensus dev-node-add prepare \
--gossip-keys true \
--tls-keys true \
--deployment "${SOLO_DEPLOYMENT}" \
--pvcs true \
--admin-key <admin-key> \
--node-alias node2 \
--output-dir context
| Flag | Description |
|---|---|
| –gossip-keys | Generate gossip keys for the new node. |
| –tls-keys | Generate gRPC TLS keys for the new node. |
| –pvcs | Create persistent volume claims for the new node. |
| –admin-key | The admin key used to authorize the node addition transaction. |
| –node-alias | Alias for the new node (e.g., node2). |
| –output-dir | Directory where prepared context files are saved for use in subsequent steps. |
Step 2: Submit the transaction to add the node
Submit the on-chain transaction to register the new node with the network:
solo consensus dev-node-add submit-transactions \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Step 3: Execute the node addition
Apply the node addition and bring the new node online:
solo consensus dev-node-add execute \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Note: For a complete walkthrough with expected outputs, see the Node Create Transaction example.
Updating a Node
You can update an existing consensus node - for example, to upgrade its software version or modify its configuration - without removing it from the network.
Step 1: Prepare the update
Stage the updated configuration and any new software version for the target node:
solo consensus dev-node-update prepare \
--deployment "${SOLO_DEPLOYMENT}" \
--node-alias node1 \
--consensus-node-version v0.66.0 \
--output-dir context
| Flag | Description |
|---|---|
| –node-alias | Alias of the node to update (e.g., node1). |
| –consensus-node-version | The consensus node software version to update to. |
| –new-admin-key | (Optional) New admin key for the node’s Hedera account. Omit to keep the existing admin key. |
| –output-dir | Directory where prepared context files are saved for use in subsequent steps. |
Step 2: Submit the update transaction
Submit the on-chain transaction to register the node update with the network:
solo consensus dev-node-update submit-transactions \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Step 3: Execute the update
Apply the update and restart the node with the new configuration:
solo consensus dev-node-update execute \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Note: For a complete walkthrough with expected outputs, see the Node Update Transaction example.
Removing a Node from a Network
You can dynamically remove a consensus node from a running network without taking the remaining nodes offline.
Note: Removing a node permanently reduces the number of consensus nodes in the network. Ensure the remaining nodes meet the minimum threshold required for consensus before proceeding.
Step 1: Prepare the Node for Deletion
Stage the deletion context for the target node:
solo consensus dev-node-delete prepare \
--deployment "${SOLO_DEPLOYMENT}" \
--node-alias node2 \
--output-dir context
| Flag | Description |
|---|---|
| –node-alias | Alias of the node to remove (e.g., node2). |
| –output-dir | Directory where prepared context files are saved for use in subsequent steps. |
Step 2: Submit the delete transaction
Submit the on-chain transaction to deregister the node from the network:
solo consensus dev-node-delete submit-transactions \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Step 3: Execute the deletion
Remove the node and clean up its associated resources:
solo consensus dev-node-delete execute \
--deployment "${SOLO_DEPLOYMENT}" \
--input-dir context
Note: For a complete walkthrough with expected outputs, see the Node Delete Transaction example.
2.2.6 - Consensus Node Environment Variables
Overview
Solo lets you define environment variables for consensus nodes with an
application.env file, passed through the --application-env flag. The
consensus node start script loads this file when it launches the JVM, so every
variable defined in it is visible to the Java process.
Variables that are only set on the node container, for example through custom
Helm chart values, are not forwarded to the Java process. If you need a variable
such as MALLOC_ARENA_MAX to be present in the running JVM environment, define
it in application.env.
The application.env file
Write the variables as plain KEY=VALUE lines. Blank lines and lines starting
with # are ignored:
# Limit glibc malloc arenas to reduce memory fragmentation.
MALLOC_ARENA_MAX=4
JAVA_OPTS=-XX:+UseG1GC -XX:MaxDirectMemorySize=128M
Pass the file to solo consensus network deploy:
solo consensus network deploy \
--deployment "${SOLO_DEPLOYMENT}" \
--application-env ./config/application.env
Solo stages your file as the application.env ConfigMap for the consensus
nodes. The file replaces Solo’s default application.env content, so include
every variable your nodes require.
Solo also sets the same variables on the node container, so the container environment and the JVM environment stay consistent without any extra configuration.
Verifying the JVM environment
To confirm a variable reached the running Java process, inspect the process environment inside the root container:
kubectl exec -n "${SOLO_NAMESPACE}" network-node1-0 -c root-container -- \
sh -c 'tr "\0" "\n" < /proc/$(pgrep java)/environ | grep MALLOC_ARENA_MAX'
The command prints MALLOC_ARENA_MAX=4 when the variable is in effect and
prints nothing when it is not.
Falcon values file
For One-shot Falcon deployments, put the same flag under the network section:
network:
--application-env: './config/application.env'
For the complete list of Falcon network flags, see the Falcon Values File Reference.
2.3 - Subprocess Environment Filtering
Overview
Solo runs external commands on your behalf — helm, kubectl, kind, docker/podman,
npm, gh and brew. It does not hand those commands your whole environment. Each
command receives only the variables it is known to need, built from an allowlist.
The reason is that Solo is frequently run from a shell or CI runner holding credentials that have nothing to do with deploying a network — registry tokens, cloud keys, SSH agent sockets. Passing the whole environment would forward all of it to every tool, and onward to anything those tools spawn: Helm plugins, kubectl credential plugins, package lifecycle scripts.
Filtering is deliberately deny-by-default. A variable that is not on the allowlist is not forwarded, even if it looks harmless.
Checking whether a variable was withheld
Solo records what it filtered. Search your Solo log for the variable name:
grep MY_VARIABLE ~/.solo/logs/solo.log
Select-String -Path "$HOME\.solo\logs\solo.log" -Pattern "MY_VARIABLE"
Solo writes a summary line followed by one or more lines carrying the names, so your variable
appears on a withheld from line rather than in the summary:
[19:45:49.621] INFO: Withheld 83 environment variable(s) from 'helm' commands because they are not on the allowlist for that command:
[19:45:49.621] INFO: withheld from 'helm': AI_AGENT, APPLICATION_INSIGHTS_NO_STATSBEAT, ..., MY_VARIABLE, ...
Searching for the variable name finds the second line, which also tells you which command withheld
it. To see everything withheld from one command instead, search for withheld from 'helm'.
This is logged at info, so it is present in the log by default — you do not need to re-run
with --debug. It is emitted once per command type per run, and long lists are split across
several lines so that every name remains searchable.
Two bounds apply, so that a hostile or unusual environment cannot forge log entries or fill your disk:
- Names are only listed if they look like ordinary identifiers (letters, digits,
_,.,-,(), up to 64 characters). Anything else is counted rather than printed — the line ends with something like(3 with non-identifier names omitted). - At most 2000 names are listed per command type. Beyond that the line ends with
(N further name(s) omitted). No ordinary environment comes close to this; if you hit it, the variable is still filtered exactly as described, it is simply not enumerated.
If your variable is not listed but also is not reaching the tool, forward it explicitly as below — the two bounds above affect only what is reported, never what is forwarded.
If your config file is present but unusable — malformed YAML, unreadable, or with permissions Solo will not trust — Solo fails with an error naming the file rather than starting up as if the file were not there. A setting you believe is applied but silently is not would be worse than a clear failure.
If your variable is in that list and the tool needs it, forward it explicitly as below.
Forwarding an additional variable
Add the exact variable name to subprocess.additionalEnvironmentVariables in your Solo
config file — ~/.solo/solo-config.yaml — under the command that needs it:
subprocess:
additionalEnvironmentVariables:
helm:
- MY_PLATFORM_SETTING
kubectl:
- MY_PLATFORM_SETTING
Recognised command keys are generic, kubectl, helm, kind, containerEngine, brew,
npm and githubCli.
The file is solo-config.yaml in your Solo home directory. It is optional — if you do not have
one, nothing changes. Create it if it is not already there.
The default location is ~/.solo (%USERPROFILE%\.solo on Windows). Override it with
SOLO_HOME:
export SOLO_HOME=/path/to/solo-home
ls -l "$SOLO_HOME/solo-config.yaml"
$env:SOLO_HOME = "C:\path\to\solo-home"
Get-Item "$env:SOLO_HOME\solo-config.yaml" | Format-List Name, Length, LastWriteTime
The similarly named ~/.solo/solo.yaml is a leftover from older Solo versions and holds an
unrelated flags: structure. Some test tooling deletes it automatically, so settings placed
there would be lost. Use solo-config.yaml.
Scope and syntax rules
- Exact names only. Wildcards and prefixes are not supported.
AWS_*will not work; list each name. - Per command. A variable listed under
helmreacheshelmonly. There is no “all commands” list — a variable a credential plugin needs has no business reachingnpmor a container engine. - Config file only. Unlike every other Solo setting, this one cannot be set through a
SOLO_*environment variable. A setting that relaxes environment filtering must not itself be controllable by the environment being filtered. Attempts to set it via the environment are ignored, with a warning.
Names that are always refused
Some variables are refused no matter what the config file says, because they change how a spawned tool loads code, whom it trusts, or where it fetches credentials. Solo logs a warning naming each refused entry rather than ignoring it silently.
| Family | Examples |
|---|---|
| Loader and interpreter hooks | LD_PRELOAD, LD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES, NODE_OPTIONS, BASH_ENV, PYTHONPATH, PERL5OPT, RUBYOPT, PS4, GIT_SSH_COMMAND, EDITOR |
| TLS trust overrides | SSL_CERT_FILE, SSL_CERT_DIR, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, AWS_CA_BUNDLE, NODE_TLS_REJECT_UNAUTHORIZED |
| Credential and endpoint redirection | AWS_ENDPOINT_URL and every AWS_ENDPOINT_URL_<SERVICE> form such as AWS_ENDPOINT_URL_STS, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE, AZURE_CLIENT_SECRET |
Matching is case-insensitive, and the LD_, DYLD_ and AWS_ENDPOINT_URL families are refused
by prefix rather than by exact name — AWS_ENDPOINT_URL_STS in particular takes precedence over
the global endpoint setting and would otherwise redirect the EKS credential exchange.
These would let anyone able to write your Solo config file run arbitrary code inside a process holding cluster-admin, or silently intercept traffic to your Kubernetes API server.
subprocess.additionalEnvironmentVariables extends what Solo forwards to helm and kubectl,
so anyone able to edit the file can widen what those commands receive. Because you create
this file, Solo does not own its permissions — it checks them instead, and refuses to apply the
settings with an error if the file itself is a symbolic link, is not owned by you, or is writable
by group or other users. It applies a similar check to the directories above the file, and reads
the file through a descriptor opened without following symlinks, validating that descriptor rather
than the path.
What that does and does not guarantee, stated precisely:
- The file itself — on POSIX only — is checked and read through the same descriptor, so its contents cannot be swapped between the check and the read. On Windows there is no equivalent no-follow open, so the symlink check is a check-then-open and carries a small race; see the Windows note below.
- The directories above it are checked for a static misconfiguration — a group-writable
SOLO_HOME, for instance. This is not race-free: someone who already has write access to one of those directories could replace a component between the check and the open. Closing that would require component-by-component opens, which Node’s filesystem API does not offer. - On POSIX the directory walk reaches the filesystem root, and accepts directories owned by you or
by root, plus sticky directories such as
/tmp. On Windows it stops before the volume root, becauseC:\legitimately carries broad write grants.
In short: this protects you from a misconfigured or shared SOLO_HOME, not from an attacker who
already holds write access somewhere on the path to it.
Keep both owner-only:
# Secure the directory as well as the file: write access to the directory is enough to
# replace the file inside it. Solo also checks every parent directory up to the filesystem root.
chmod 700 ~/.solo
chmod 600 ~/.solo/solo-config.yaml
# NTFS ACLs replace POSIX mode bits. Secure the directory as well as the file: write access to
# the directory is enough to replace the file inside it.
icacls "$HOME\.solo" /inheritance:r /grant:r "$($env:USERNAME):(OI)(CI)F"
icacls "$HOME\.solo\solo-config.yaml" /inheritance:r /grant:r "$($env:USERNAME):(F)"
On Windows, Solo reads the DACL with icacls and refuses the file if any principal other than
you, SYSTEM, Administrators or CREATOR OWNER holds write access. Inherit-only entries are
ignored, since they apply to items created later rather than to the path itself.
The ACL checks described here are implemented but have not been exercised on a real Windows
machine — only reasoned about and unit-tested on POSIX. The Windows guarantee is also weaker: the
volume root is not inspected, and the symlink check on the file is a check-then-open rather than
an atomic no-follow open. Do not rely on subprocess.additionalEnvironmentVariables on Windows
yet; please report what you find if you try it.
Managed Kubernetes and workload identity
Solo forwards the variables the AWS credential plugin needs, so EKS IRSA works without any configuration:
AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_REGION, AWS_DEFAULT_REGION,
AWS_STS_REGIONAL_ENDPOINTS, AWS_PROFILE
GKE and AKS are not yet covered. The variables their credential plugins need have not been verified against a real cluster, and adding unverified names risks both breakage and security holes, so they are not in the built-in allowlist. Until they are verified, forward them yourself:
subprocess:
additionalEnvironmentVariables:
kubectl:
- GOOGLE_APPLICATION_CREDENTIALS
- USE_GKE_GCLOUD_AUTH_PLUGIN
helm:
- GOOGLE_APPLICATION_CREDENTIALS
- USE_GKE_GCLOUD_AUTH_PLUGIN
If you confirm the required set for GKE or AKS on a real cluster, please open an issue on hiero-ledger/solo so it can be added to the built-in allowlist.
Note that AZURE_AUTHORITY_HOST and AWS_ENDPOINT_URL are intentionally excluded from the
built-in list: they redirect which authority or endpoint the credential plugin contacts.
Sovereign clouds that genuinely need a non-default authority can add AZURE_AUTHORITY_HOST
explicitly, which makes it a deliberate local decision rather than something inherited silently
from the surrounding environment.
See also
- Using Environment Variables — variables that configure Solo itself, as opposed to the ones Solo passes on to external tools.
2.4 - Attach JVM Debugger and Retrieve Logs
Overview
This guide covers three debugging workflows:
- Retrieve logs from a running consensus node using k9s or the Solo CLI
- Attach a JVM debugger in IntelliJ IDEA to a running or restarting node
- Save and restore network state files to replay scenarios across sessions
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness — your local environment meets all hardware and software requirements.
- Quickstart — you have a running Solo cluster and are familiar with the basic Solo workflow.
You will also need:
- k9s installed (
brew install k9s) - IntelliJ IDEA with a Remote JVM Debug run configuration (for JVM debugging only)
- A local checkout of
hiero-consensus-node
that has been built with
assembleorbuild(for JVM debugging only)
1. Retrieve Consensus Node Logs
Using k9s
Run k9s -A in your terminal to open the cluster dashboard, then select one
of the network node pods.

Select the root-container and press s to open a shell inside the container.

Navigate to the Hedera application directory to browse logs and configuration:
cd /opt/hgcapp/services-hedera/HapiApp2.0/
From there you can inspect logs and configuration files:
[root@network-node1-0 HapiApp2.0]# ls -ltr data/config/
total 0
lrwxrwxrwx 1 root root 27 Dec 4 02:05 bootstrap.properties -> ..data/bootstrap.properties
lrwxrwxrwx 1 root root 29 Dec 4 02:05 application.properties -> ..data/application.properties
lrwxrwxrwx 1 root root 32 Dec 4 02:05 api-permission.properties -> ..data/api-permission.properties
[root@network-node1-0 HapiApp2.0]# ls -ltr output/
total 1148
-rw-r--r-- 1 hedera hedera 0 Dec 4 02:06 hgcaa.log
-rw-r--r-- 1 hedera hedera 0 Dec 4 02:06 queries.log
drwxr-xr-x 2 hedera hedera 4096 Dec 4 02:06 transaction-state
drwxr-xr-x 2 hedera hedera 4096 Dec 4 02:06 state
-rw-r--r-- 1 hedera hedera 190 Dec 4 02:06 swirlds-vmap.log
drwxr-xr-x 2 hedera hedera 4096 Dec 4 16:01 swirlds-hashstream
-rw-r--r-- 1 hedera hedera 1151446 Dec 4 16:07 swirlds.log
Using the Solo CLI (Alternative option)
To download hgcaa.log and swirlds.log as a zip archive without entering
the container shell, run:
# Downloads logs to ~/.solo/logs/<namespace>/<timestamp>
solo deployment diagnostics all --deployment solo-deployment
2. Attach a JVM Debugger in IntelliJ IDEA
Solo supports pausing node startup at a JDWP debug port so you can attach IntelliJ IDEA before the node begins processing transactions.
Configure IntelliJ IDEA
Create a Remote JVM Debug run configuration in IntelliJ IDEA.
For the Hedera Node application:

If you are working on the Platform test application instead:

Set any breakpoints you need before launching the Solo command in the next step.
Note: The
local-build-pathin the commands below references../hiero-consensus-node/hedera-node/data. Adjust this path to match your local checkout location. Ensure the directory is up to date by running./gradlew assemblein thehiero-consensus-noderepo before proceeding.
Example 1 — Debug a node during initial network deployment
This example deploys a three-node network and pauses node2 for debugger
attachment.
SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment
# Remove any previous state to avoid name collision issues
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}
solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --debug-node-alias node2
When Solo reaches the active-check phase for node2, it pauses and displays:
❯ Check all nodes are ACTIVE
Check node: node1,
Check node: node2, Please attach JVM debugger now.
Check node: node3,
? JVM debugger setup for node2. Continue when debugging is complete? (y/N)
At this point, launch the remote debug configuration in IntelliJ IDEA. The node will stop at your breakpoint:


When you are done debugging, resume execution in IntelliJ, then type y in
the terminal to allow Solo to continue.
Example 2 — Debug a node during a node add operation
This example starts a three-node network and then attaches a debugger while
adding node4.
SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}
solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --pvcs
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node add --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys \
--debug-node-alias node4 \
--local-build-path ../hiero-consensus-node/hedera-node/data \
--pvcs
Example 3 — Debug a node during a node update operation
This example attaches a debugger to node2 while it restarts as part of an
update operation.
SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}
solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node update --deployment "${SOLO_DEPLOYMENT}" \
--node-alias node2 \
--debug-node-alias node2 \
--local-build-path ../hiero-consensus-node/hedera-node/data \
--new-account-number 0.0.7 \
--gossip-public-key ./s-public-node2.pem \
--gossip-private-key ./s-private-node2.pem \
--consensus-node-version v0.71.0
Example 4 — Debug a node during a node delete operation
This example attaches a debugger to node3 while node2 is being removed
from the network.
SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}
solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node destroy --deployment "${SOLO_DEPLOYMENT}" \
--node-alias node2 \
--debug-node-alias node3 \
--local-build-path ../hiero-consensus-node/hedera-node/data
3. Save and Restore Network State
You can snapshot the state of a running network and restore it later. This is useful for replaying specific scenarios or sharing reproducible test cases with the team.
Save state
Stop the nodes first, then download the state archives:
# Stop all nodes before downloading state
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"
# Download state files to ~/.solo/logs/<namespace>/
solo consensus state download -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"
The state files are saved under ~/.solo/logs/:
└── logs
├── solo-deployment
│ ├── network-node1-0-state.zip
│ └── network-node2-0-state.zip
└── solo.log
Restore state
Create a fresh cluster, deploy the network, then upload the saved state before starting the nodes:
SOLO_CLUSTER_NAME=solo-cluster
SOLO_NAMESPACE=solo-deployment
SOLO_CLUSTER_SETUP_NAMESPACE=solo-setup
SOLO_DEPLOYMENT=solo-deployment
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo cluster-ref config setup -s "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect --cluster-ref ${SOLO_CLUSTER_NAME} --context kind-${SOLO_CLUSTER_NAME}
solo deployment config create --namespace "${SOLO_NAMESPACE}" --deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach --deployment "${SOLO_DEPLOYMENT}" --cluster-ref ${SOLO_CLUSTER_NAME} --num-consensus-nodes 3
solo keys consensus generate --deployment "${SOLO_DEPLOYMENT}" --gossip-keys --tls-keys -i node1,node2,node3
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3 --local-build-path ../hiero-consensus-node/hedera-node/data
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2,node3
solo consensus node stop --deployment "${SOLO_DEPLOYMENT}"
# Upload previously saved state files
solo consensus node state download -i node1,node2,node3 --deployment "${SOLO_DEPLOYMENT}"
# Restart the network using the uploaded state
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" --state-file network-node1-0-state.zip
2.5 - One-Shot Deploy with Custom Component Versions
Overview
Solo’s one-shot single deploy and one-shot multi deploy commands accept
an --edge flag that switches every component from its built-in stable
default to a separate set of “edge” versions. Each edge version is read from
an environment variable at startup, so you can pin any component to any tag
the container registry exposes — including release candidates and unreleased
builds — without editing Solo source or rebuilding the CLI.
Use this guide when you need to:
- Test a Hiero Consensus Node release candidate against the rest of the Solo-managed stack.
- Reproduce a specific component version combination for a bug report or regression test.
- Iterate on a single component (Mirror Node, Relay, Explorer, …) while the other components stay on stable defaults.
For the canonical list of *_EDGE_VERSION variables, see
Edge Component Versions
in the environment variables reference.
Local binary builds vs published version overrides:
--edgeand*_EDGE_VERSIONvariables pin components to published container image tags — they require the image to exist in the registry. If you need to deploy a binary you compiled locally (before any tag or release exists), use--local-build-pathinstead.
How It Works
*_EDGE_VERSION env var (e.g. CONSENSUS_NODE_EDGE_VERSION)
│
▼
solo one-shot ... deploy --edge
│
▼
Each component is pinned to its edge version for this deploy.
Components without an explicit override fall back to the compiled-in
edge defaults, which themselves fall back to the stable defaults.
- Without
--edge, Solo uses the stable defaults compiled into the CLI. - With
--edge, Solo reads the*_EDGE_VERSIONconstants — and any matching environment variable you set in the shell overrides those constants.
You only need to set variables for the components you want to override. All others fall back to their compiled-in defaults.
Image cache: Because you pin versions with environment variables, Solo’s image cache pulls the matching image versions automatically. Pinning a version with a
--*-versionCLI flag (or insolo.config.yaml) instead does not update the cache — it would pull the default versions and cause a cache miss on first deploy. Use the environment variables shown here to keep the cache aligned with the deployed versions.
Quick Start
Deploy a single-node network with a custom Consensus Node release candidate:
CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1 \
solo one-shot single deploy --edge --debug
What this does:
CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1overrides the consensus node version for this command invocation.--edgetells Solo to read*_EDGE_VERSIONvariables instead of stable defaults.--debugenables Solo’s debug mode — appropriate for local development, not for production-shaped deployments.- Mirror Node, Relay, Explorer, Block Node, and the Solo chart keep their
compiled-in edge defaults because no
*_EDGE_VERSIONwas set for them.
Note: Every successive
solo one-shot single deploycommand will remove the existing components and will create a new deployment.
Deprecated: The
--devflag has been renamed to--debug.--devstill works as an alias but is deprecated and prints a warning; update your scripts to use--debug. The--devalias will no longer be supported once Solo0.82.0reaches its end of support date.
Where to Find Version Tags
Each *_EDGE_VERSION value is a published release tag from the component’s
GitHub release page. Pick a tag from the appropriate page below, and match
the format the component publishes — a missing or extra v prefix is the
most common cause of image-pull failures.
| Component | Release tags | Format | Example |
|---|---|---|---|
| Consensus Node | hiero-consensus-node | vMAJOR.MINOR.PATCH[-qualifier] | v0.74.0-rc.1 |
| Mirror Node | hiero-mirror-node | vMAJOR.MINOR.PATCH | v0.153.1 |
| JSON-RPC Relay | hiero-json-rpc-relay | MAJOR.MINOR.PATCH | 0.77.0 |
| Explorer | hiero-mirror-node-explorer | MAJOR.MINOR.PATCH | 27.0.0 |
| Block Node | hiero-block-node | vMAJOR.MINOR.PATCH[-qualifier] | v0.32.0 |
| Solo Chart | hashgraph/solo-charts | MAJOR.MINOR.PATCH | 0.64.0 |
Note: Consensus Node, Mirror Node, and Block Node tags are prefixed with
v; Relay, Explorer, and Solo Chart tags are not. The tag must exist in the component’s container registry, otherwise the deploy fails with an image-pull error — see Troubleshooting.
Command Reference
In Solo v0.72.0, --edge is accepted by the single and multi one-shot
deploy variants. solo one-shot falcon deploy does not currently accept
--edge — use one of the two variants below to test custom component
versions.
Single-node deploy
CONSENSUS_NODE_EDGE_VERSION=<version> \
MIRROR_NODE_EDGE_VERSION=<version> \
solo one-shot single deploy --edge [--debug] [other flags]
Multi-node deploy
CONSENSUS_NODE_EDGE_VERSION=<version> \
MIRROR_NODE_EDGE_VERSION=<version> \
solo one-shot multi deploy --edge --num-consensus-nodes 3 [--debug] [other flags]
Examples
Override Consensus Node and Mirror Node
CONSENSUS_NODE_EDGE_VERSION=v0.73.0 \
MIRROR_NODE_EDGE_VERSION=v0.153.1 \
solo one-shot single deploy --edge --debug
Override every component
CONSENSUS_NODE_EDGE_VERSION=v0.73.0 \
MIRROR_NODE_EDGE_VERSION=v0.153.1 \
RELAY_EDGE_VERSION=0.77.0 \
EXPLORER_EDGE_VERSION=27.0.0 \
BLOCK_NODE_EDGE_VERSION=v0.32.0 \
SOLO_CHART_EDGE_VERSION=0.64.0 \
solo one-shot single deploy --edge --debug
Export once, reuse across a development session
If you are iterating and running deploy/destroy/deploy cycles, export the
variables so every one-shot command in the shell session picks them up:
export CONSENSUS_NODE_EDGE_VERSION=v0.74.0-rc.1
export MIRROR_NODE_EDGE_VERSION=v0.153.1
solo one-shot single deploy --edge --debug
# Destroy and redeploy without re-typing the variables
solo one-shot single destroy
solo one-shot single deploy --edge --debug
Verifying the Versions in Use
After the deploy starts, confirm the resolved versions in the structured Solo log:
tail -f $HOME/.solo/logs/solo.ndjson | jq '.msg, .version // empty'
Note: Use
solo.ndjson(newline-delimited JSON, machine-readable) forjqpipes. The companionsolo.logis pino-pretty formatted text and will not parse as JSON.
Inspect the deployed Helm releases and their chart versions:
helm list -A
helm get values <release-name> -n <namespace>
Confirm the consensus node container image tag:
kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
Replace <namespace> with your deployment namespace (default one-shot —
see Find your deployment namespace).
Without --edge
Omitting --edge uses the stable defaults compiled into the Solo CLI you are
running — any *_EDGE_VERSION variables you have set are ignored for that
invocation.
# Stable defaults — *_EDGE_VERSION variables are ignored.
solo one-shot single deploy --debug
If you want to pin versions without using --edge (for example, to test a
specific stable release of one component), see
Pinning Component Versions
in the environment variables reference.
Troubleshooting
The version I set is not being used.
Confirm you passed --edge. Without it, Solo ignores every *_EDGE_VERSION
variable and uses the compiled-in stable defaults.
Solo is ignoring my environment variable.
The variable must be exported in (or prefixed to) the same shell process that runs Solo. Verify with:
echo $CONSENSUS_NODE_EDGE_VERSION # should print your value
If you set the variable inline (FOO=bar solo ...), double-check the variable
name is spelled exactly as listed in
Edge Component Versions
— the names are case-sensitive.
The deploy fails with an image-pull error.
The tag you supplied does not exist in the component’s container registry, or
the format is wrong (missing v prefix, extra spaces, …). Cross-check the tag
against the official release list for that component before retrying.
The deploy starts but a component crashes immediately.
Different component versions are not guaranteed to be mutually compatible. When mixing edge versions, prefer combinations Solo’s CI already exercises (see the Version Compatibility Reference).
2.6 - Customizing Solo with Tasks
Overview
The Task tool (task) is a task runner that enables you to deploy and customize Solo networks using infrastructure-as-code patterns. Rather than running individual Solo CLI commands, you can use predefined Taskfile targets to orchestrate complex deployment workflows with a single command.
This guide covers installing the Task tool, understanding available Taskfile targets, and using them to deploy networks with various configurations. It also points to maintained example projects that demonstrate common Solo workflows.
Note: This guide assumes you have cloned the Solo repository and have basic familiarity with command-line interfaces and Docker.
Prerequisites
Before you begin, ensure you have completed the following:
- System Readiness: Prepare your local environment (Docker, Kind, Kubernetes, and related tooling).
- Quickstart: You are familiar with the basic Solo workflow and the
solo one-shot single deploycommand.
Tip: Task-based workflows are ideal for developers who want to:
- Run the same deployment multiple times reliably.
- Customize network components (add mirror nodes, relays, block nodes, etc.).
- Use version control to track deployment configurations.
- Integrate Solo deployments into CI/CD pipelines.
Install the Task Tool
The Task tool is a dependency for using Taskfile targets in the Solo repository. Install it using one of the following methods:
Using Homebrew (macOS/Linux) (recommended)
brew install go-task/tap/go-task
Using npm
npm install -g @go-task/cli
Verify the installation:
task --version
Expected output:
Task version: v3.X.X
Using package managers
Visit the Task installation guide for additional installation methods for your operating system.
Understanding the Task Structure
The Solo repository uses a modular Task architecture located in the scripts/ directory:
scripts/
├── Taskfile.yml # Main entry point (includes other Taskfiles)
├── Taskfile.scripts.yml # Core deployment and management tasks
├── Taskfile.examples.yml # Example project tasks
├── Taskfile.release.yml # Package publishing tasks
└── [other helper scripts]
How to Run Tasks
From the root directory or any example directory, run:
# Run the default task
task
# Run a specific task
task <task-name>
# Run tasks with variables
task <task-name> -- VAR_NAME=value
Deploy Network Configurations
Basic Network Deployment
Deploy a standalone Hiero Consensus Node network with a single command:
# From the repository root, navigate to scripts directory
cd scripts
# Deploy default network (2 consensus nodes)
task default
This command performs the following actions:
- Initializes Solo and downloads required dependencies.
- Creates a local Kubernetes cluster using Kind.
- Deploys 2 consensus nodes.
- Sets up gRPC and JSON-RPC endpoints for client access.
Deploy Network with Mirror Node
Deploy a network with a consensus node, mirror node, and Hiero Explorer:
cd scripts
task default-with-mirror
This configuration includes:
| Component | Description |
|---|---|
| Consensus Node | 2 consensus nodes running Hiero |
| Mirror Node | Stores and serves historical transaction data |
| Explorer UI | Web interface for viewing accounts |
Access the Explorer at: http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier). See Port availability if the port is in use.
Deploy Network with Relay and Explorer
Deploy a network with consensus nodes, mirror node, explorer, and JSON-RPC relay for Ethereum-compatible access:
cd scripts
task default-with-relay
This configuration includes:
| Component | Description |
|---|---|
| Consensus Node | 2 consensus nodes running Hiero |
| Mirror Node | Stores and serves historical transaction data |
| Explorer UI | Web interface for viewing accounts |
| JSON-RPC Relay | Ethereum-compatible JSON-RPC interface |
Access the services at (Solo 0.63+ defaults; for Solo 0.62 and earlier use the legacy ports in parentheses):
- Explorer:
http://localhost:38080/localnet/dashboard(legacy:http://localhost:8080/localnet/dashboard) - JSON-RPC Relay:
http://localhost:37546(legacy:http://localhost:7546)
See Port availability if a port is already in use on your machine.
Available Taskfile Targets
The Taskfile includes a comprehensive set of targets for deploying and managing Solo networks. Below are the most commonly used targets, organized by category.
Core Deployment Targets
These targets handle the primary deployment lifecycle:
| Task | Description |
|---|---|
default | Complete deployment workflow for Solo |
install | Initialize cluster, create deployment, and setup consensus net |
destroy | Tear down the consensus network |
clean | Full cleanup: destroy network, remove cache, logs, and files |
start | Start all consensus nodes |
stop | Stop all consensus nodes |
Example: Deploy, then clean up
cd scripts
# Deploy the network
task default
# ... (use the network)
# Stop the network
task stop
# Remove all traces of the deployment
task clean
Cache and Log Cleanup
When cleaning up, you can selectively remove specific components:
| Task | Description |
|---|---|
clean:cache | Remove the Solo cache directory (~/.solo/cache) |
clean:logs | Remove the Solo logs directory (~/.solo/logs) |
clean:tmp | Remove temporary deployment files |
Mirror Node Management
Add, configure, or remove mirror nodes from an existing deployment:
| Task | Description |
|---|---|
solo:mirror-node | Add a mirror node to the current deployment |
solo:destroyer-mirror-node | Remove the mirror node from the deployment |
Example: Add mirror node to running network
cd scripts
# Start with a basic network
task default
# Add mirror node later
task solo:mirror-node
# Remove mirror node
task solo:destroyer-mirror-node
Explorer UI Management
Deploy or remove the Hiero Explorer for transaction/account viewing:
| Task | Description |
|---|---|
solo:explorer | Add explorer UI to the current deployment |
solo:destroy-explorer | Remove explorer UI from the deployment |
Example: Deploy network with explorer
cd scripts
task default
task solo:explorer
# Access at http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier)
JSON-RPC Relay Management
Deploy or remove the Relay for Ethereum-compatible access:
| Task | Description |
|---|---|
solo:relay | Add JSON-RPC relay to the current deployment |
solo:destroy-relay | Remove JSON-RPC relay from the deployment |
Example: Add relay to running network
cd scripts
task default-with-mirror
task solo:relay
# Access JSON-RPC at http://localhost:37546 (Solo 0.63+) or http://localhost:7546 (Solo 0.62 and earlier)
Block Node Management
Deploy or remove block nodes for streaming block data:
| Task | Description |
|---|---|
solo:block:add | Add a block node to the current deployment |
solo:block:destroy | Remove the block node from the deployment |
Example: Deploy network with block node
cd scripts
task default
task solo:block:add
# Block node will stream block data
Infrastructure Tasks
Low-level tasks for managing clusters and network infrastructure:
| Task | Description |
|---|---|
cluster:create | Create a Kind (Kubernetes in Docker) cluster |
cluster:destroy | Delete the Kind cluster |
solo:cluster:setup | Setup cluster infrastructure and prerequisites |
solo:deployment:create | Create a new deployment configuration |
solo:deployment:attach | Attach an existing cluster to a deployment |
solo:network:deploy | Deploy the consensus network to the cluster |
solo:network:destroy | Destroy the consensus network |
Tip: Unless you need custom cluster management, use the higher-level tasks like
default,install, ordestroywhich orchestrate these infrastructure tasks automatically.
Utility Tasks
Helpful tasks for inspecting and managing running networks:
| Task | Description |
|---|---|
show:ips | Display the external IPs of all network nodes |
solo:node:logs | Retrieve logs from consensus nodes |
solo:freeze:restart | Execute a freeze/restart upgrade workflow for testing version upgrades |
Example: View network IPs and logs
cd scripts
# See which nodes are running and their IPs
task show:ips
# Retrieve node logs for debugging
task solo:node:logs
Database Tasks
Deploy external databases for specialized configurations:
| Task | Description |
|---|---|
solo:external-database | Setup external PostgreSQL database with Helm |
Advanced Configuration with Environment Variables
You can customize Task behavior by setting environment variables before running tasks. Common variables include:
| Variable | Description | Default |
|---|---|---|
SOLO_NETWORK_SIZE | Number of consensus nodes | 1 |
SOLO_NAMESPACE | Kubernetes namespace | solo-e2e |
CONSENSUS_NODE_VERSION | Consensus node version | v0.65.1 |
MIRROR_NODE_VERSION | Mirror node version | v0.138.0 |
RELAY_VERSION | JSON-RPC Relay version | v0.70.0 |
EXPLORER_VERSION | Explorer UI version | v25.1.1 |
For a comprehensive reference of all available environment variables, see Using Environment Variables.
Example: Deploy with custom versions
cd scripts
# Deploy with specific component versions
CONSENSUS_NODE_VERSION=v0.66.0 \
MIRROR_NODE_VERSION=v0.139.0 \
task default-with-mirror
Example Projects
The Solo repository includes 14+ maintained example projects that demonstrate common Solo workflows. These examples serve as templates and starting points for custom implementations.
Getting Started with Examples
Each example is located in the examples/ directory and includes:
- Pre-configured
Taskfile.ymlwith deployment settings. init-containers-values.yamlfor customization.- Example-specific README with detailed instructions.
To run an example:
cd examples/<example-name>
# Deploy the example
task
# Clean up when done
task clean
Available Examples
Network Setup Examples
- Address Book: Use Yahcli to pull ledger and mirror node address books for querying network state
- Network with Domain Names: Setup a network with custom domain names for nodes instead of IP addresses
- Network with Block Node: Deploy a network with block node for streaming block data (example coming soon)
Configuration Examples
- Local Build with Custom Config: Deploy using a locally-built consensus node with custom configuration
- Consensus Node JVM Parameters: Customize JVM parameters (memory, GC settings, etc.) for consensus nodes
Database Examples
- External Database Test: Deploy Solo with an external PostgreSQL database instead of embedded storage
- Multi-Cluster Backup and Restore: Backup state from one cluster and restore to another using external database
State Management Examples
- State Save and Restore: Save the network state with mirror node, then restore to a new deployment
- Version Upgrade Test: Upgrade all network components to the current version to test compatibility
Node Transaction Examples
These examples demonstrate manual operations for adding, modifying, and removing nodes:
- Node Create Transaction: Create a new node manually using the NodeCreate transaction
- Node Update Transaction: Update an existing node configuration with NodeUpdate transaction
- Node Delete Transaction: Remove a node from the network with NodeDelete transaction
Integration Examples
- Hardhat with Solo: Test smart contracts locally with Hardhat using Solo as the test network
- One-Shot Falcon Deployment: One-shot deployment using Falcon (consensus node implementation)
- One-Shot Local Build: One-shot deployment using a locally-built consensus node
Testing Examples
- Rapid-Fire: Rapid-fire deployment and teardown commands for stress testing the deployment workflow
- Running Solo Inside Cluster: Deploy Solo within an existing Kubernetes cluster instead of creating a new one
Practical Workflows
Workflow 1: Quick Development Network with Logging
Deploy a network for development and debugging:
cd scripts
# Set logging level (PowerShell: $env:SOLO_LOG_LEVEL = 'debug')
export SOLO_LOG_LEVEL=debug
# Deploy with mirror and relay
task default-with-relay
# Retrieve logs if needed
task solo:node:logs
# View network endpoints
task show:ips
# Clean up
task clean
Workflow 2: Test Configuration Changes
Iterate on network configuration using any example with a Taskfile.yml:
cd examples/local-build-with-custom-config
# Edit the Taskfile or init-containers-values.yaml
# Deploy with your changes
task
# Test your configuration
# Clean up and try again
task clean
Workflow 3: Upgrade Network Components
Test upgrading Solo components:
cd examples/version-upgrade-test
# Deploy with current versions
task
# The example automatically tests the upgrade path
# Clean up
task clean
Workflow 4: Backup and Restore Network State
Test disaster recovery and state migration:
cd examples/state-save-and-restore
# Deploy initial network with state
task
# The example includes backup/restore operations
# Clean up
task clean
Troubleshooting
Common Issues
Task command not found
Ensure Task is installed and on your PATH:
which task
task --version
Taskfile not found
Run Task commands from the scripts/ directory or an examples/ subdirectory where a Taskfile.yml exists:
cd scripts
task default
Insufficient resources
Some deployments require significant resources. Verify your Docker has at least 12 GB of memory and 6 CPU cores allocated:
docker info --format 'CPU: {{.NCPU}}, Memory: {{.MemTotal | div 1000000000}}GB'
Cluster cleanup issues
If the cluster becomes unstable, perform a full cleanup:
cd scripts
# Remove all traces
task clean
# As a last resort, manually delete the Kind cluster
kind delete cluster --name solo-e2e
Next Steps
After deploying a network with Task, explore:
- Using the JavaScript SDK: Interact with your network programmatically
- Using Network Load Generator: Stress test your network
- Environment Variables Reference: Fine-tune deployment behavior
- Solo CI Workflow: Integrate Solo deployments into CI/CD pipelines
Additional Resources
2.7 - GitHub Actions CI Integration
Overview
solo one-shot single deploy is self-contained and runs the same way in CI as
it does locally. It creates a Kind cluster if one does not already exist,
installs all required tools internally, and exits once every component is healthy.
Which runner type do you need?
- GitHub-hosted (
ubuntu-latest) - GitHub provides and manages the machine. Most common for open-source and public repos. Choose this if your workflow usesruns-on: ubuntu-latest.- Self-hosted runners - you manage the machine (your own server, cloud VM, or on-prem hardware). Choose this if your workflow uses
runs-on: self-hostedor a custom runner label, or if you need explicit control over Kind version and resource allocation.Not sure which type you have? If you’re using a standard GitHub account without dedicated runner infrastructure, you’re on GitHub-hosted runners.
GitHub-Hosted Runners
If your workflow has
runs-on: ubuntu-latest, this is your section.
Solo handles Kind cluster creation internally - you do not need to pre-create a cluster.
The workflow steps are:
- Checkout your repository code.
- Install Node.js (v22) and Solo CLI (pinned version).
- Deploy the network with
solo one-shot single deploy. - Verify the Mirror REST API is reachable - Solo exits when components are healthy, but the Mirror Node REST API may need a few extra seconds to become reachable from the host. This step polls until it is ready before your tests run.
- Run your tests against the live network.
- Destroy the network (
if: always()ensures cleanup runs even on failure). - Upload logs for post-run debugging.
Important: Pin
@hiero-ledger/solo@<version>to a specific release. Unpinned (@latest) installs may pick up breaking changes and cause unexpected workflow failures.
Example Workflow
name: "Integration Tests"
on:
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
defaults:
run:
shell: bash
permissions:
contents: read
jobs:
integration-tests:
name: Integration Tests
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Solo CLI
run: |
npm install -g @hiero-ledger/solo@<version>
solo --version
- name: One-Shot Single Deploy
run: solo one-shot single deploy
- name: Verify Mirror REST API
timeout-minutes: 5
run: |
echo "Waiting for mirror node REST API..."
for i in $(seq 1 30); do
response=$(curl -sf http://localhost:38081/api/v1/accounts 2>/dev/null || true)
if echo "${response}" | grep -q '"accounts"'; then
echo "Mirror REST API is up."
exit 0
fi
echo "Attempt ${i}/30: not ready, retrying in 10s..."
sleep 10
done
echo "ERROR: Mirror REST API did not become available."
exit 1
# Add your integration test steps here
- name: One-Shot Single Destroy
if: always()
run: solo one-shot single destroy --quiet-mode || true
- name: Upload Logs
if: always()
uses: actions/upload-artifact@v4
with:
name: solo-logs
path: ~/.solo/logs/*
overwrite: true
if-no-files-found: warn
Self-Hosted Runners
If your workflow has
runs-on: self-hostedor a custom runner label, this is your section.
Use this setup when you manage the runner machine yourself and need explicit control over Kind version, cluster name, or resource allocation.
Runner Requirements
Solo requires a minimum of 6 CPU cores and 12 GB of memory on the runner. If these requirements are not met, Solo components may hang or fail during deployment.
Note: The Kubernetes cluster does not have full access to all host memory. Setting Docker to 12 GB means Kind will have access to less than 12 GB. Memory and CPU utilisation also increase over time as transaction load grows.
To verify that your runner meets the requirements, add this step to your workflow:
- name: Check Docker Resources
run: |
read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
echo "CPU cores: $cpus"
echo "Memory: ${mem_gb} GB"
Step 1: Set Up Kind
Install Kind with pinned versions to ensure reproducible builds.
- name: Setup Kind
uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
with:
install_only: true
node_image: kindest/node:v1.32.2@sha256:3966f21e12b760f6585bde7140cae5e8cdc0e52b37a6f90ce39834b6e72e3f49
version: v0.29.0
kubectl_version: v1.32.2
verbosity: 3
wait: 120s
Important: Kind v0.29.0 or later and Kubernetes v1.32.2 or later are required. Solo enforces these minimum versions at runtime.
Step 2: Install Node.js
- name: Set up Node.js
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with:
node-version: 22.12.0
Step 3: Install Solo CLI
Important: Always pin the CLI version. Unpinned installs may pick up breaking changes from newer releases and cause unexpected workflow failures.
- name: Install Solo CLI
run: |
set -euo pipefail
npm install -g @hiero-ledger/solo@<version>
solo --version
kind --version
Step 4: Deploy Solo
- name: Deploy Solo
env:
SOLO_CLUSTER_NAME: solo
SOLO_DEPLOYMENT: solo-deployment
run: |
set -euo pipefail
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo one-shot single deploy --deployment "${SOLO_DEPLOYMENT}" | tee solo-deploy.log
Cleanup
After the workflow completes, destroy the Solo deployment and delete the Kind
cluster. Use if: always() on the destroy step so cleanup runs even when an
earlier step fails.
- name: Destroy Solo deployment
if: always()
env:
SOLO_DEPLOYMENT: solo-deployment
run: |
set -euo pipefail
solo one-shot single destroy --deployment "${SOLO_DEPLOYMENT}"
- name: Delete Kind cluster
if: always()
env:
SOLO_CLUSTER_NAME: solo
run: |
set -euo pipefail
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
Complete Example Workflow
name: Solo CI Example
on:
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
jobs:
test:
runs-on: self-hosted
timeout-minutes: 30
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Check Docker Resources
run: |
read cpus mem <<<"$(docker info --format '{{.NCPU}} {{.MemTotal}}')"
mem_gb=$(awk -v m="$mem" 'BEGIN{printf "%.1f", m/1000000000}')
echo "CPU cores: $cpus"
echo "Memory: ${mem_gb} GB"
- name: Setup Kind
uses: helm/kind-action@a1b0e391336a6ee6713a0583f8c6240d70863de3
with:
install_only: true
node_image: kindest/node:v1.32.2@sha256:3966f21e12b760f6585bde7140cae5e8cdc0e52b37a6f90ce39834b6e72e3f49
version: v0.29.0
kubectl_version: v1.32.2
verbosity: 3
wait: 120s
- name: Set up Node.js
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with:
node-version: 22.12.0
- name: Install Solo CLI
run: |
set -euo pipefail
npm install -g @hiero-ledger/solo@<version>
solo --version
kind --version
- name: Deploy Solo
env:
SOLO_CLUSTER_NAME: solo
SOLO_DEPLOYMENT: solo-deployment
run: |
set -euo pipefail
kind create cluster -n "${SOLO_CLUSTER_NAME}"
solo one-shot single deploy --deployment "${SOLO_DEPLOYMENT}" | tee solo-deploy.log
# Add your integration test steps here
- name: Destroy Solo deployment
if: always()
env:
SOLO_DEPLOYMENT: solo-deployment
run: |
set -euo pipefail
solo one-shot single destroy --deployment "${SOLO_DEPLOYMENT}"
- name: Delete Kind cluster
if: always()
env:
SOLO_CLUSTER_NAME: solo
run: |
set -euo pipefail
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
- name: Upload Logs
if: always()
uses: actions/upload-artifact@v4
with:
name: solo-logs
path: ~/.solo/logs/*
overwrite: true
if-no-files-found: warn
Resetting Between Tests
If your job runs multiple test suites that each need a clean genesis ledger, you do not need to destroy and redeploy between them. Reset the ledger to genesis after each suite to return to a known starting state without recreating the cluster:
- name: Reset ledger to genesis
env:
SOLO_DEPLOYMENT: solo-deployment
run: |
set -euo pipefail
solo ledger system reset --deployment "${SOLO_DEPLOYMENT}"
This applies to both runner types and is significantly faster than a destroy-and-redeploy cycle. See Reset the ledger to genesis for details and available flags.
2.8 - Run Performance Tests Locally
Overview
This guide shows how to run the Solo E2E performance test on a local machine.
Prerequisites
task,node,npm,kubectl, andkindinstalled- Docker running
- Solo dependencies installed (
npm ci)
Run the Performance Test
From the repository root:
task test-setup
task test-e2e-performance
The test uses one-shot single deploy/destroy flow and then runs rapid-fire load tests.
What Gets Tested
The test suite runs four sequential load tests using the Network Load Generator
(NLG), each for 5 minutes by default (controlled by
ONE_SHOT_METRICS_TEST_DURATION_IN_MINUTES):
| Load Test | What it submits |
|---|---|
TokenTransferLoadTest | Fungible token transfers |
NftTransferLoadTest | NFT transfers |
CryptoTransferLoadTest | HBAR crypto transfers |
HCSLoadTest | Hedera Consensus Service (HCS) messages |
All four tests target a max of 100 TPS with 5 concurrent threads and 1,000 accounts. After all load tests complete, the suite sleeps for one additional metrics-collection window to capture steady-state resource usage.
Metrics Measured
The test collects two categories of metrics:
Workload metrics (per load test)
| Metric | Unit | Description |
|---|---|---|
| TPS | transactions/second | Throughput achieved by the NLG during the load window |
| Transaction count | count | Total transactions submitted in the load window |
| End-to-end mirror RTT | milliseconds | Time from transaction submission to visibility in the Mirror Node REST API |
| RTT percentiles (p50, p95, max) | milliseconds | Distribution of 5 RTT probe samples taken concurrently during each load test |
Kubernetes resource metrics (polled every 5 seconds)
| Metric | Unit | Description |
|---|---|---|
| CPU | millicores | Aggregate CPU across all pods in the test namespace |
| Memory | MiB | Aggregate memory across all pods in the test namespace |
| Peak CPU | millicores | Highest CPU snapshot recorded across the full test run |
| Peak memory | MiB | Highest memory snapshot recorded across the full test run |
Per-pod breakdowns are included in the JSON output for post-run analysis.
Expected Output
Console output (per load test)
A healthy run prints a green result line after each load test:
TokenTransferLoadTest: TPS 100 (30000 transactions in 300 sec), RTT 450 ms
TokenTransferLoadTest: end-to-end mirror RTT max 499 ms (p50 320 ms, p95 480 ms, 5 samples)
During the post-test metrics collection window you will see:
performance-tests: sleeping for metrics collection, 1 of 5 minutes
performance-tests: sleeping for metrics collection, 2 of 5 minutes
...
performance-tests: sleeping for metrics collection, 5 of 5 minutes
Summary JSON
After the test completes, a summary is written to
~/.solo/logs/<namespace>.json. The example below shows the structure and
fields — actual values will differ based on your hardware and Solo version:
{
"snapshotName": "performance-tests-3712495",
"date": "2026-07-28T10:15:42.123Z",
"gitHubSha": "",
"soloVersion": "0.85.0",
"soloChartVersion": "0.65.0",
"consensusNodeVersion": "v0.74.0",
"mirrorNodeVersion": "0.159.0",
"blockNodeVersion": "0.38.0",
"relayVersion": "0.77.0",
"explorerVersion": "26.1.0",
"cpuInMillicores": 1842,
"memoryInMebibytes": 2331,
"runtimeInMinutes": 62,
"transactionCount": 120000,
"events": [
"Starting TokenTransferLoadTest",
"Starting NftTransferLoadTest",
"Starting CryptoTransferLoadTest",
"Starting HCSLoadTest",
"Completed all performance tests"
],
"peakCpuInMillicores": 2100,
"peakCpuSnapshot": "performance-tests-3712495",
"peakMemoryInMebibytes": 2331,
"peakMemorySnapshot": "performance-tests-3712495",
"clusterMetrics": ["..."]
}
A full timeline of all 5-second snapshots is written to
~/.solo/logs/<namespace>/timeline-metrics.json for trend analysis.
Interpreting Results
Healthy indicators
| Signal | What to look for |
|---|---|
| All four load tests print a green result line | TPS reported as non-zero |
events array ends with "Completed all performance tests" | All tests ran to completion |
memoryInMebibytes under 3,000 MiB | CI threshold — above this indicates a regression |
| End-to-end mirror RTT under 600 ms | RTT probe target; values near or above this indicate mirror node lag |
Problem indicators
| Signal | Likely cause |
|---|---|
A load test prints no result line or exits with NO_RESULT | NLG pod failed to start or crashed mid-run |
| TPS is 0 with 0 transactions | Consensus node was unreachable or rejected all transactions |
memoryInMebibytes above 3,000 MiB | Memory regression — compare per-pod breakdown in clusterMetrics to identify the culprit |
| RTT consistently above 600 ms | Mirror node importer lag; check importer pod logs |
events array is missing later entries | Test timed out or threw before completing all load tests |
Note: The
SmartContractLoadTestis currently disabled (it.skip) pending an upstream fix and will not appear in results.
Optional: Use a Local Consensus Node Build
If you already have a local consensus node build, set SOLO_LOCAL_BUILD_PATH so
commands that consume --local-build-path can use it by default:
export SOLO_LOCAL_BUILD_PATH="/absolute/path/to/hiero-consensus-node/hedera-node/data"
task test-setup
task test-e2e-performance
Optional: Shorten Test Duration
You can shorten load-test duration while iterating:
export ONE_SHOT_METRICS_TEST_DURATION_IN_MINUTES=2
task test-e2e-performance
Run the GitHub Performance Workflow for a Branch
You can run the repository performance workflow against any pushed Solo branch.
Option 1: Using gh CLI
export SOLO_BRANCH="<your-branch-name>"
gh workflow run "Performance Test Solo Deployment" --ref "${SOLO_BRANCH}" --repo hiero-ledger/solo
Watch the latest run for that branch:
RUN_ID=$(gh run list --workflow "Performance Test Solo Deployment" --branch "${SOLO_BRANCH}" --limit 1 --json databaseId -q '.[0].databaseId')
gh run watch "${RUN_ID}" --repo hiero-ledger/solo
Option 2: Using GitHub Web UI
- Open
https://github.com/hiero-ledger/solo/actions/workflows/flow-performance-test.yaml. - Click
Run workflow. - Select your branch in the branch dropdown.
- Click
Run workflowto start the run.
2.9 - CLI Reference
Canonical Solo CLI command and flag reference for end users.
Legacy-to-current Solo CLI command mappings for users migrating from pre-v0.44 command paths.
2.9.1 - Solo CLI Reference
Overview
This page is the canonical command reference for the Solo CLI.
- Use it to look up command paths, subcommands, and flags.
- Use
solo <command> --helpandsolo <command> <subcommand> --helpfor runtime help on your installed version. - For legacy command mappings, see CLI Migration Reference.
Output Formats (--output, -o)
Solo supports machine-readable output for version output and for command execution flows that honor the output format flag.
solo --version -o json
solo --version -o yaml
solo --version -o wide
Expected formats:
json: JSON object output.yaml: YAML output.wide: plain text value-oriented output.
Global Flags
Global flags shown in root help:
--dev: enable developer mode.--force-port-forward: force port forwarding for network services.-v,--version: print Solo version.
Deprecated Features
Deprecated flags are also marked inline in the help output below as [deprecated], and deprecated commands as [DEPRECATED: ...]. The version window and replacement for each are listed in the table.
| Feature | Type | Deprecated for commands | Deprecated since | Planned removal | Replacement |
|---|---|---|---|---|---|
--image-tag | flag | • block node: add | v0.85.0 | v0.91.0 | --component-image |
--relay-release | flag | • relay node: add, upgrade• one-shot single: deploy• one-shot multi: deploy• one-shot falcon: deploy, prepare | v0.85.0 | v0.91.0 | --relay-version |
--release-tag | flag | • block node: add• consensus network: deploy• consensus node: setup, refresh, add, update, destroy• consensus dev-node-add: prepare, submit-transactions, execute• consensus dev-node-update: prepare, submit-transactions, execute• consensus dev-node-delete: prepare, submit-transactions, execute• one-shot falcon: prepare | v0.85.0 | v0.91.0 | --consensus-node-version |
--chart-version | flag | • block node: add• one-shot single: deploy• one-shot multi: deploy• one-shot falcon: deploy, prepare | v0.85.0 | v0.91.0 | --block-node-version |
--wraps | flag | • consensus network: deploy | v0.94.0 | v0.100.0 | — |
--wraps-key-path | flag | • consensus network: deploy, upgrade• consensus node: start, restart, add, update• consensus dev-node-add: prepare, submit-transactions, execute• consensus dev-node-update: prepare, submit-transactions, execute | v0.94.0 | v0.100.0 | — |
EXPERIMENTAL_COPY_WRAPS_LIB_IN_PARALLEL | environment-variable | v0.94.0 | v0.100.0 | — | |
CHECK_WRAPS_DIRECTORY_MAX_ATTEMPTS | environment-variable | v0.94.0 | v0.100.0 | — | |
CHECK_WRAPS_DIRECTORY_BACKOFF_MS | environment-variable | v0.94.0 | v0.100.0 | — | |
SOLO_TSS_WRAPS_ARTIFACTS-FOLDER-NAME | environment-variable | v0.94.0 | v0.100.0 | — | |
SOLO_TSS_WRAPS_DIRECTORY-NAME | environment-variable | v0.94.0 | v0.100.0 | — | |
SOLO_TSS_WRAPS_ALLOWED-KEY-FILES | environment-variable | v0.94.0 | v0.100.0 | — | |
SOLO_TSS_WRAPS_LIBRARY-DOWNLOAD-URL | environment-variable | v0.94.0 | v0.100.0 | — | |
SOLO_TSS_WRAPS_LIBRARY_DOWNLOAD_URL | environment-variable | v0.94.0 | v0.100.0 | — | |
consensus dev-node-add | command | v0.94.0 | v0.100.0 | consensus node add | |
consensus dev-node-update | command | v0.94.0 | v0.100.0 | consensus node update | |
consensus dev-node-upgrade | command | v0.94.0 | v0.100.0 | consensus network upgrade | |
consensus dev-node-delete | command | v0.94.0 | v0.100.0 | consensus node destroy | |
consensus dev-freeze | command | v0.94.0 | v0.100.0 | consensus network freeze | |
init | command | v0.85.0 | v0.91.0 | — |
Command and Flag Reference
The sections below are generated from Solo CLI help output using the implementation on hiero-ledger/solo.
Version Output
******************************* Solo *********************************************
Version : 0.97.0
**********************************************************************************
Root Help Output
Usage:
solo <command> [options]
Commands:
config Backup and restore component configurations for Solo deployments. These commands display what would be backed up or restored without performing actual operations.
block Block Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
cluster-ref Manages the relationship between Kubernetes context names and Solo cluster references which are an alias for a kubernetes context.
consensus Consensus Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
deployment Create, modify, and delete deployment configurations. Deployments are required for most of the other commands.
explorer Explorer Node operations for creating, modifying, and destroying resources.These commands require the presence of an existing deployment.
init Initialize local environment [DEPRECATED: since v0.85.0, removal v0.91.0]
keys Consensus key generation operations
ledger System, Account, and Crypto ledger-based management operations. These commands require an operational set of consensus nodes and may require an operational mirror node.
mirror Mirror Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
relay RPC Relay Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
cache Manage solo cached items.
one-shot One Shot commands for new and returning users who need a preset environment type. These commands use reasonable defaults to provide a single command out of box experience.
rapid-fire Commands for performing load tests a Solo deployment
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
config
config
Backup and restore component configurations for Solo deployments. These commands display what would be backed up or restored without performing actual operations.
Commands:
config ops Configuration backup and restore operations
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
config ops
config ops
Configuration backup and restore operations
Commands:
config ops backup Create a backup for all component configurations of a deployment. Create a zip file with configuration and log data.Export states, configmaps and secrets
config ops restore-config Restore component configurations from backup. Imports ConfigMaps, Secrets, logs, and state files for a running deployment.
config ops restore-clusters Restore Kind clusters from backup directory structure. Creates clusters, sets up Docker network, installs MetalLB, and initializes cluster configurations. Does not deploy network components.
config ops restore-network Deploy network components to existing clusters from backup. Deploys consensus nodes, block nodes, mirror nodes, explorers, and relay nodes. Requires clusters to be already created (use restore-clusters first).
config ops restore-db Restore the external database dump independently of restore-config. Run this before restore-network so mirror, relay, and explorer deploy against an already-populated database.
config ops bridge-import-gap Bridge a mirror importer record_file gap after restore and restart the importer.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
config ops backup
config ops backup
Create a backup for all component configurations of a deployment. Create a zip file with configuration and log data.Export states, configmaps and secrets
Options:
--backup-external-database Export external Mirror Node [boolean] [default: false]
database dump during backup
and save connection/credential
parameters to JSON
--debug , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--external-db-params-file Path to external database [string]
parameters JSON. Backup writes
it; restore reads it to avoid
passing many DB flags
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--output-dir Path to the directory where [string]
the command context will be
saved to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
--zip-file Path to the encrypted backup [string]
ZIP archive used during
restore
--zip-password Password to encrypt generated [string]
backup ZIP archives
config ops restore-config
config ops restore-config
Restore component configurations from backup. Imports ConfigMaps, Secrets, logs, and state files for a running deployment.
Options:
--debug , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--external-db-params-file Path to external database [string]
parameters JSON. Backup writes
it; restore reads it to avoid
passing many DB flags
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--input-dir Path to the directory where [string]
the command context will be
loaded from
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
config ops restore-clusters
config ops restore-clusters
Restore Kind clusters from backup directory structure. Creates clusters, sets up Docker network, installs MetalLB, and initializes cluster configurations. Does not deploy network components.
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--metallb-config Path pattern for MetalLB [string] [default: "metallb-cluster-{index}.yaml"]
configuration YAML files
(supports {index} placeholder
for cluster number)
--options-file Path to YAML file containing [string]
component-specific deployment
options (consensus, block,
mirror, relay, explorer)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
--zip-file Path to the encrypted backup [string]
ZIP archive used during
restore
--zip-password Password to encrypt generated [string]
backup ZIP archives
config ops restore-network
config ops restore-network
Deploy network components to existing clusters from backup. Deploys consensus nodes, block nodes, mirror nodes, explorers, and relay nodes. Requires clusters to be already created (use restore-clusters first).
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--debug , --dev Enable [boolean] [default: false]
debug mode
--expected-lb-ips-file Path to KEY=VALUE file with [string]
expected LoadBalancer IP
mappings, for example
KIND_<CONTEXT>_NETWORK_NODE1_SVC=172.x.x.x
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--options-file Path to YAML file containing [string]
component-specific deployment
options (consensus, block,
mirror, relay, explorer)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--realm Realm number. Requires [number] [default: 0]
network-node > v61.0 for
non-zero values
--shard Shard number. Requires [number] [default: 0]
network-node > v61.0 for
non-zero values
--skip-ip-tracking Skip LoadBalancer IP tracking [boolean] [default: true]
and enforcement during
restore-network
-v, --version Show version number [boolean]
config ops restore-db
config ops restore-db
Restore the external database dump independently of restore-config. Run this before restore-network so mirror, relay, and explorer deploy against an already-populated database.
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--debug , --dev Enable [boolean] [default: false]
debug mode
--external-db-params-file Path to external database [string]
parameters JSON. Backup writes
it; restore reads it to avoid
passing many DB flags
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
config ops bridge-import-gap
config ops bridge-import-gap
Bridge a mirror importer record_file gap after restore and restart the importer.
Options:
--debug , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--external-db-params-file Path to external database [string]
parameters JSON. Backup writes
it; restore reads it to avoid
passing many DB flags
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
block
block
Block Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
Commands:
block node Create, manage, or destroy block node instances. Operates on a single block node instance at a time.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
block node
block node
Create, manage, or destroy block node instances. Operates on a single block node instance at a time.
Commands:
block node add Creates and configures a new block node instance for the specified deployment using the specified Kubernetes cluster. The cluster must be accessible and attached to the specified deployment.
block node destroy Destroys a single block node instance in the specified deployment. Requires access to all Kubernetes clusters attached to the deployment.
block node upgrade Upgrades a single block node instance in the specified deployment. Requires access to all Kubernetes clusters attached to the deployment.
block node add-external Add an external block node for the specified deployment. You can specify the priority and consensus nodes to which to connect or use the default settings.
block node delete-external Deletes an external block node from the specified deployment.
block node collect-jfr Downloads the Java Flight Recorder recording from a block node instance in the specified deployment to the local solo logs directory. Requires the block node to have been deployed with Java Flight Recorder enabled.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
block node add
block node add
Creates and configures a new block node instance for the specified deployment using the specified Kubernetes cluster. The cluster must be accessible and attached to the specified deployment.
Options:
--block-node-chart-dir Block node local chart [string]
directory path (e.g.
~/hiero-block-node/charts)
--block-node-message-size-hard-limit-bytes Hard limit, in bytes, for [number]
block node connection message
size in block-nodes.json
--block-node-message-size-soft-limit-bytes Soft limit, in bytes, for [number]
block node connection message
size in block-nodes.json
--block-node-tss-overlay Force-apply block-node TSS [boolean] [default: false]
values overlay when deploying
block nodes before consensus
deployment sets tssEnabled in
remote config.
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--chart-version Block node chart version [deprecated] [string] [default: "0.44.3"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image [string]
Docker image override.
Supports a published registry
reference (e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--enable-ingress enable ingress on the [boolean] [default: false]
component/pod
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--image-tag Overrides the Docker image tag [deprecated] [string]
(e.g. 0.36.0-SNAPSHOT).
--priority-mapping Configure block node priority [string]
mapping. Unlisted nodes will
not be routed to a block node
Default: all consensus nodes
included, first node priority
is 2. Example:
"priority-mapping
node1=2,node2=1"
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
block node destroy
block node destroy
Destroys a single block node instance in the specified deployment. Requires access to all Kubernetes clusters attached to the deployment.
Options:
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
block node upgrade
block node upgrade
Upgrades a single block node instance in the specified deployment. Requires access to all Kubernetes clusters attached to the deployment.
Options:
--block-node-chart-dir Block node local chart [string]
directory path (e.g.
~/hiero-block-node/charts)
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--upgrade-version Version to be used for the [string]
upgrade
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
block node add-external
block node add-external
Add an external block node for the specified deployment. You can specify the priority and consensus nodes to which to connect or use the default settings.
Options:
--address Provide external block node [string] [required]
address (IP or domain), with
optional port (Default port:
40840) Examples: " --address
localhost:8080", " --address
192.0.0.1"
--block-node-message-size-hard-limit-bytes Hard limit, in bytes, for [number]
block node connection message
size in block-nodes.json
--block-node-message-size-soft-limit-bytes Soft limit, in bytes, for [number]
block node connection message
size in block-nodes.json
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--priority-mapping Configure block node priority [string]
mapping. Unlisted nodes will
not be routed to a block node
Default: all consensus nodes
included, first node priority
is 2. Example:
"priority-mapping
node1=2,node2=1"
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
block node delete-external
block node delete-external
Deletes an external block node from the specified deployment.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
block node collect-jfr
block node collect-jfr
Downloads the Java Flight Recorder recording from a block node instance in the specified deployment to the local solo logs directory. Requires the block node to have been deployed with Java Flight Recorder enabled.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref
cluster-ref
Manages the relationship between Kubernetes context names and Solo cluster references which are an alias for a kubernetes context.
Commands:
cluster-ref config List, create, manage, and remove associations between Kubernetes contexts and Solo cluster references.
cluster-ref state Detect, start, and stop the local container engine (Docker Desktop / Podman machine) and the Kind cluster containers it hosts.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cluster-ref config
cluster-ref config
List, create, manage, and remove associations between Kubernetes contexts and Solo cluster references.
Commands:
cluster-ref config connect Creates a new internal Solo cluster name to a Kubernetes context or maps a Kubernetes context to an existing internal Solo cluster reference
cluster-ref config disconnect Removes the Kubernetes context associated with an internal Solo cluster reference.
cluster-ref config list Lists the configured Kubernetes context to Solo cluster reference mappings.
cluster-ref config info Displays the status information and attached deployments for a given Solo cluster reference mapping.
cluster-ref config setup Setup cluster with shared components
cluster-ref config reset Uninstall shared components from cluster
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cluster-ref config connect
cluster-ref config connect
Creates a new internal Solo cluster name to a Kubernetes context or maps a Kubernetes context to an existing internal Solo cluster reference
Options:
-c, --cluster-ref The cluster reference that [string] [required]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--context The Kubernetes context name to [string] [required]
be used
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref config disconnect
cluster-ref config disconnect
Removes the Kubernetes context associated with an internal Solo cluster reference.
Options:
-c, --cluster-ref The cluster reference that [string] [required]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref config list
cluster-ref config list
Lists the configured Kubernetes context to Solo cluster reference mappings.
Options:
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref config info
cluster-ref config info
Displays the status information and attached deployments for a given Solo cluster reference mapping.
Options:
-c, --cluster-ref The cluster reference that [string] [required]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref config setup
cluster-ref config setup
Setup cluster with shared components
Options:
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
-s, --cluster-setup-namespace Cluster Setup Namespace [string] [default: "solo-setup"]
--debug , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--grafana-alloy Deploy Grafana Alloy and Loki [boolean] [default: false]
to collect and store pod logs
--metrics-server Deploy metrics server to [boolean] [default: false]
enable kubectl top for CPU and
memory usage monitoring
--minio Deploy minio operator [boolean] [default: true]
--prometheus-stack Deploy prometheus stack [boolean] [default: false]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
cluster-ref config reset
cluster-ref config reset
Uninstall shared components from cluster
Options:
-c, --cluster-ref The cluster reference that [string] [required]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
-s, --cluster-setup-namespace Cluster Setup Namespace [string] [default: "solo-setup"]
--debug , --dev Enable [boolean] [default: false]
debug mode
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref state
cluster-ref state
Detect, start, and stop the local container engine (Docker Desktop / Podman machine) and the Kind cluster containers it hosts.
Commands:
cluster-ref state start Starts the container engine (Docker Desktop / Podman machine), then starts any stopped Kind cluster containers belonging to the configured cluster references. Already running containers are left untouched.
cluster-ref state stop Stops the running Kind cluster containers belonging to the configured cluster references, freeing local resources. Kind clusters not managed by Solo are left untouched.
cluster-ref state info Displays the container engine state and the state of every Kind cluster container on the machine, marking which ones belong to a Solo cluster reference.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cluster-ref state start
cluster-ref state start
Starts the container engine (Docker Desktop / Podman machine), then starts any stopped Kind cluster containers belonging to the configured cluster references. Already running containers are left untouched.
Options:
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref state stop
cluster-ref state stop
Stops the running Kind cluster containers belonging to the configured cluster references, freeing local resources. Kind clusters not managed by Solo are left untouched.
Options:
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cluster-ref state info
cluster-ref state info
Displays the container engine state and the state of every Kind cluster container on the machine, marking which ones belong to a Solo cluster reference.
Options:
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus
consensus
Consensus Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
Commands:
consensus network Ledger/network wide consensus operations such as freeze, upgrade, and deploy. Operates on the entire ledger and all consensus node instances.
consensus node List, create, manage, or destroy consensus node instances. Operates on a single consensus node instance at a time.
consensus state List, download, and upload consensus node state backups to/from individual consensus node instances.
consensus dev-node-add Dev operations for adding consensus nodes. [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node add]
consensus dev-node-update Dev operations for updating consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node update]
consensus dev-node-upgrade Dev operations for upgrading consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus network upgrade]
consensus dev-node-delete Dev operations for delete consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node destroy]
consensus dev-freeze Dev operations for freezing consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus network freeze]
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus network
consensus network
Ledger/network wide consensus operations such as freeze, upgrade, and deploy. Operates on the entire ledger and all consensus node instances.
Commands:
consensus network deploy Installs and configures all consensus nodes for the deployment.
consensus network destroy Removes all consensus network components from the deployment.
consensus network freeze Initiates a network freeze for scheduled maintenance or upgrades
consensus network upgrade Upgrades the software version running on all consensus nodes.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus network deploy
consensus network deploy
Installs and configures all consensus nodes for the deployment.
Options:
--api-permission-properties api-permission.properties file [string] [default: "templates/api-permission.properties"]
for node
--app Testing app name [string] [default: "HederaNode.jar"]
--application-env the application.env file for [string] [default: "templates/application.env"]
the node provides environment
variables to the
solo-container to be used when
the hedera platform is started
--application-properties application.properties file [string] [default: "templates/application.properties"]
for node (default merges with
Solo defaults; add comment
'SOLO_ENABLE_OVERWRITE=true'
in the file to use overwrite
mode)
--aws-bucket name of aws storage bucket [string]
--aws-bucket-prefix path prefix of aws storage [string]
bucket
--aws-bucket-region name of aws bucket region [string]
--aws-endpoint aws storage endpoint URL [string]
--aws-write-access-key aws storage access key for [string]
write access
--aws-write-secrets aws storage secret key for [string]
write access
--backup-bucket name of bucket for backing up [string]
state files
--backup-endpoint backup storage endpoint URL [string]
--backup-provider backup storage service [string] [default: "GCS"]
provider, GCS or AWS
--backup-region backup storage region [string] [default: "us-central1"]
--backup-write-access-key backup storage access key for [string]
write access
--backup-write-secrets backup storage secret key for [string]
write access
--block-node-message-size-hard-limit-bytes Hard limit, in bytes, for [number]
block node connection message
size in block-nodes.json
--block-node-message-size-soft-limit-bytes Soft limit, in bytes, for [number]
block node connection message
size in block-nodes.json
--bootstrap-properties bootstrap.properties file for [string] [default: "templates/bootstrap.properties"]
node
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-s, --cluster-setup-namespace Cluster Setup Namespace [string] [default: "solo-setup"]
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--enable-monitoring-support Enables CRDs for Prometheus [boolean] [default: true]
and Grafana.
--envoy-ips IP mapping where key = value [string]
is node alias and static ip
for envoy proxy, (e.g.:
--envoy-ips
node1=127.0.0.1,node2=127.0.0.1)
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gcs-bucket name of gcs storage bucket [string]
--gcs-bucket-prefix path prefix of google storage [string]
bucket
--gcs-endpoint gcs storage endpoint URL [string]
--gcs-write-access-key gcs storage access key for [string]
write access
--gcs-write-secrets gcs storage secret key for [string]
write access
--genesis-throttles-file throttles.json file used [string]
during network genesis
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--grpc-tls-cert TLS Certificate path for the [string]
gRPC (e.g.
"node1=/Users/username/node1-grpc.cert" with multiple nodes comma separated)
--grpc-tls-key TLS Certificate key path for [string]
the gRPC (e.g.
"node1=/Users/username/node1-grpc.key" with multiple nodes comma separated)
--grpc-web-tls-cert TLS Certificate path for gRPC [string]
Web (e.g.
"node1=/Users/username/node1-grpc-web.cert" with multiple nodes comma separated)
--grpc-web-tls-key TLC Certificate key path for [string]
gRPC Web (e.g.
"node1=/Users/username/node1-grpc-web.key" with multiple nodes comma separated)
--haproxy-ips IP mapping where key = value [string]
is node alias and static ip
for haproxy, (e.g.:
--haproxy-ips
node1=127.0.0.1,node2=127.0.0.1)
--jfr-config Java Flight Recorder [string]
configuration file path
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--log4j2-xml log4j2.xml file for node [string] [default: "templates/log4j2.xml"]
--network-node-ips IP mapping where key = value [string]
is node alias and static ip
for the network-node
LoadBalancer service, (e.g.:
--network-node-ips
node1=127.0.0.1,node2=127.0.0.2)
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
--pod-log Install PodLog custom resource [boolean] [default: false]
for monitoring Network Node
pod logs
--pvcs Enable persistent volume [boolean] [default: false]
claims to store data outside
the pod, required for
consensus node add
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--service-monitor Install ServiceMonitor custom [boolean] [default: false]
resource for monitoring
Network Node metrics
--settings-txt settings.txt file for node [string] [default: "templates/settings.txt"]
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--storage-type storage type for saving stream [default: "minio_only"]
files, available options are
minio_only, aws_only,
gcs_only, aws_and_gcs
--tss Enable hinTS/TSS (CN >= [boolean] [default: true]
v0.74).
-f, --values-file Comma separated chart values [string]
file paths for each cluster
(e.g.
values.yaml,cluster-1=./a/b/values1.yaml,cluster-2=./a/b/values2.yaml)
--verify-pvc-mounts Fail the deployment when a [boolean] [default: false]
persistent volume claim is
mounted on storage smaller
than it requested; requires
--pvcs
-v, --version Show version number [boolean]
--wraps Enable recursive WRAPs [deprecated] [boolean] [default: false]
aggregation for hinTS/TSS (CN
>= v0.72).
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus network destroy
consensus network destroy
Removes all consensus network components from the deployment.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--delete-pvcs Delete the persistent volume [boolean] [default: false]
claims. If both --delete-pvcs
and --delete-secrets are
set to true, the namespace
will be deleted.
--delete-secrets Delete the network secrets. If [boolean] [default: false]
both --delete-pvcs and
--delete-secrets are set to
true, the namespace will be
deleted.
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--enable-timeout enable time out for running a [boolean] [default: false]
command
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus network freeze
consensus network freeze
Initiates a network freeze for scheduled maintenance or upgrades
Options:
--debug , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--freeze-block-drain-seconds Seconds to wait after [number] [default: 20]
consensus nodes reach
FREEZE_COMPLETE before
stopping them, allowing the
block stream to drain to the
block node
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus network upgrade
consensus network upgrade
Upgrades the software version running on all consensus nodes.
Options:
--api-permission-properties api-permission.properties file [string] [default: "templates/api-permission.properties"]
for node
--app Testing app name [string] [default: "HederaNode.jar"]
--application-env the application.env file for [string] [default: "templates/application.env"]
the node provides environment
variables to the
solo-container to be used when
the hedera platform is started
--application-properties application.properties file [string] [default: "templates/application.properties"]
for node (default merges with
Solo defaults; add comment
'SOLO_ENABLE_OVERWRITE=true'
in the file to use overwrite
mode)
--bootstrap-properties bootstrap.properties file for [string] [default: "templates/bootstrap.properties"]
node
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--freeze-block-drain-seconds Seconds to wait after [number] [default: 20]
consensus nodes reach
FREEZE_COMPLETE before
stopping them, allowing the
block stream to drain to the
block node
--local-build-path path of hedera local repo [string]
--log4j2-xml log4j2.xml file for node [string] [default: "templates/log4j2.xml"]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--settings-txt settings.txt file for node [string] [default: "templates/settings.txt"]
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-start Skip starting consensus nodes [boolean] [default: false]
after staging a freeze upgrade
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
--upgrade-version Version to be used for the [string]
upgrade
--upgrade-zip-file A zipped file used for network [string]
upgrade
-f, --values-file Comma separated chart values [string]
file paths for each cluster
(e.g.
values.yaml,cluster-1=./a/b/values1.yaml,cluster-2=./a/b/values2.yaml)
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus node
consensus node
List, create, manage, or destroy consensus node instances. Operates on a single consensus node instance at a time.
Commands:
consensus node setup Setup node with a specific version of Hedera platform
consensus node start Start a node
consensus node stop Stop a node
consensus node restart Restart all nodes of the network
consensus node refresh Reset and restart a node
consensus node add Adds a node with a specific version of Hedera platform
consensus node update Update a node with a specific version of Hedera platform
consensus node destroy Delete a node with a specific version of Hedera platform
consensus node collect-jfr Collect Java Flight Recorder (JFR) files from a node for diagnostics and performance analysis. Requires the node to be running with Java Flight Recorder enabled.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus node setup
consensus node setup
Setup node with a specific version of Hedera platform
Options:
--admin-public-keys Comma separated list of DER [string]
encoded ED25519 public keys
and must match the order of
the node aliases. Solo signs
each node's updates with the
private key in that node's
<node-alias>-admin secret, so
create that secret for each
node given a key here
--app Testing app name [string] [default: "HederaNode.jar"]
--app-config json config file of testing [string]
app
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
-v, --version Show version number [boolean]
consensus node start
consensus node start
Start a node
Options:
--app Testing app name [string] [default: "HederaNode.jar"]
--debug , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--grpc-web-endpoints Configure gRPC Web endpoints [Format: <alias>=<address>[:<port>][,<alias>=<address>[:<port>]]][string]
mapping, comma separated
(Default port: 8080) (Aliases
can be provided explicitly, or
inferred by node id order)
Examples:
node1=127.0.0.1:8080,node2=127.0.0.1:8081 node1=localhost,node2=localhost:8081 localhost,127.0.0.2:8081
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--resume-from-freeze When restoring from [boolean] [default: false]
--state-file lands every node
in FREEZE_COMPLETE,
automatically restart them
once more so they resume
ACTIVE instead of staying
frozen. Only used with
--state-file . Leave unset to
restore a frozen snapshot
as-is and keep it frozen.
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--skip-grpc-web-endpoint Skip submitting the [boolean] [default: false]
NodeUpdateTransaction that
sets the gRPC web proxy
endpoint. Use during restore
when the endpoint is already
correct in the restored state
to avoid triggering TSS
re-evaluation.
--stake-amounts The amount to be staked in the [string]
same order you list the node
aliases with multiple node
staked values comma separated
--state-file A zipped state file to be used [string]
for the network
--transplant Treat the supplied state file [boolean] [default: false]
as captured on a different
network. Installs this
network's address book as
override-network.json so the
consensus node adopts it
instead of the roster carried
by the state. Leave unset when
restoring a network's own
state.
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus node stop
consensus node stop
Stop a node
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus node restart
consensus node restart
Restart all nodes of the network
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus node refresh
consensus node refresh
Reset and restart a node
Options:
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
-v, --version Show version number [boolean]
consensus node add
consensus node add
Adds a node with a specific version of Hedera platform
Options:
--admin-key Admin key [string] [default: "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"]
--app Testing app name [string] [default: "HederaNode.jar"]
--block-node-mapping Configure block-node priority [string]
mapping. Default: all
block-node included, first's
priority is 2. Unlisted
block-node will not routed to
the consensus node node.
Example: --block-node-mapping
1=2,2=1
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--envoy-ips IP mapping where key = value [string]
is node alias and static ip
for envoy proxy, (e.g.:
--envoy-ips
node1=127.0.0.1,node2=127.0.0.1)
--external-block-node-mapping Configure external-block-node [string]
priority mapping. Default: all
external-block-node included,
first's priority is 2.
Unlisted external-block-node
will not routed to the
consensus node node. Example:
--external-block-node-mapping
1=2,2=1
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-keys Generate gossip keys for nodes [boolean] [default: false]
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--grpc-tls-cert TLS Certificate path for the [string]
gRPC (e.g.
"node1=/Users/username/node1-grpc.cert" with multiple nodes comma separated)
--grpc-tls-key TLS Certificate key path for [string]
the gRPC (e.g.
"node1=/Users/username/node1-grpc.key" with multiple nodes comma separated)
--grpc-web-endpoint Configure gRPC Web endpoint [Format: <address>[:<port>]] [string]
(Default port: 8080)
--grpc-web-tls-cert TLS Certificate path for gRPC [string]
Web (e.g.
"node1=/Users/username/node1-grpc-web.cert" with multiple nodes comma separated)
--grpc-web-tls-key TLC Certificate key path for [string]
gRPC Web (e.g.
"node1=/Users/username/node1-grpc-web.key" with multiple nodes comma separated)
--haproxy-ips IP mapping where key = value [string]
is node alias and static ip
for haproxy, (e.g.:
--haproxy-ips
node1=127.0.0.1,node2=127.0.0.1)
--local-build-path path of hedera local repo [string]
--pvcs Enable persistent volume [boolean] [default: false]
claims to store data outside
the pod, required for
consensus node add
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-keys Generate gRPC TLS keys for [boolean] [default: false]
nodes
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus node update
consensus node update
Update a node with a specific version of Hedera platform
Options:
--node-alias Node alias (e.g. node99) [string] [required]
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-private-key path and file name of the [string]
private key for signing gossip
in PEM key format to be used
--gossip-public-key path and file name of the [string]
public key for signing gossip
in PEM key format to be used
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--local-build-path path of hedera local repo [string]
--new-account-number new account number for node [string]
update transaction
--new-admin-key new admin key for the Hedera [string]
account
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-private-key path and file name of the [string]
private TLS key to be used
--tls-public-key path and file name of the [string]
public TLS key to be used
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus node destroy
consensus node destroy
Delete a node with a specific version of Hedera platform
Options:
--node-alias Node alias (e.g. node99) [string] [required]
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
consensus node collect-jfr
consensus node collect-jfr
Collect Java Flight Recorder (JFR) files from a node for diagnostics and performance analysis. Requires the node to be running with Java Flight Recorder enabled.
Options:
--node-alias Node alias (e.g. node99) [string] [required]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus state
consensus state
List, download, and upload consensus node state backups to/from individual consensus node instances.
Commands:
consensus state download Downloads a signed state from consensus node/nodes.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus state download
consensus state download
Downloads a signed state from consensus node/nodes.
Options:
-i, --node-aliases Comma separated node aliases [string] [required]
(empty means all nodes)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
consensus dev-node-add
consensus dev-node-add
Dev operations for adding consensus nodes. [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node add]
Commands:
consensus dev-node-add prepare Prepares the addition of a node with a specific version of Hedera platform
consensus dev-node-add submit-transactions Submits NodeCreateTransaction and Upgrade transactions to the network nodes
consensus dev-node-add execute Executes the addition of a previously prepared node
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus dev-node-add prepare
consensus dev-node-add prepare
Prepares the addition of a node with a specific version of Hedera platform
Options:
--output-dir Path to the directory where [string] [required]
the command context will be
saved to
--admin-key Admin key [string] [default: "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"]
--app Testing app name [string] [default: "HederaNode.jar"]
--block-node-mapping Configure block-node priority [string]
mapping. Default: all
block-node included, first's
priority is 2. Unlisted
block-node will not routed to
the consensus node node.
Example: --block-node-mapping
1=2,2=1
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--external-block-node-mapping Configure external-block-node [string]
priority mapping. Default: all
external-block-node included,
first's priority is 2.
Unlisted external-block-node
will not routed to the
consensus node node. Example:
--external-block-node-mapping
1=2,2=1
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-keys Generate gossip keys for nodes [boolean] [default: false]
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--grpc-tls-cert TLS Certificate path for the [string]
gRPC (e.g.
"node1=/Users/username/node1-grpc.cert" with multiple nodes comma separated)
--grpc-tls-key TLS Certificate key path for [string]
the gRPC (e.g.
"node1=/Users/username/node1-grpc.key" with multiple nodes comma separated)
--grpc-web-endpoint Configure gRPC Web endpoint [Format: <address>[:<port>]] [string]
(Default port: 8080)
--grpc-web-tls-cert TLS Certificate path for gRPC [string]
Web (e.g.
"node1=/Users/username/node1-grpc-web.cert" with multiple nodes comma separated)
--grpc-web-tls-key TLC Certificate key path for [string]
gRPC Web (e.g.
"node1=/Users/username/node1-grpc-web.key" with multiple nodes comma separated)
--local-build-path path of hedera local repo [string]
--pvcs Enable persistent volume [boolean] [default: false]
claims to store data outside
the pod, required for
consensus node add
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-keys Generate gRPC TLS keys for [boolean] [default: false]
nodes
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-add submit-transactions
consensus dev-node-add submit-transactions
Submits NodeCreateTransaction and Upgrade transactions to the network nodes
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--app Testing app name [string] [default: "HederaNode.jar"]
--block-node-mapping Configure block-node priority [string]
mapping. Default: all
block-node included, first's
priority is 2. Unlisted
block-node will not routed to
the consensus node node.
Example: --block-node-mapping
1=2,2=1
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--external-block-node-mapping Configure external-block-node [string]
priority mapping. Default: all
external-block-node included,
first's priority is 2.
Unlisted external-block-node
will not routed to the
consensus node node. Example:
--external-block-node-mapping
1=2,2=1
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-keys Generate gossip keys for nodes [boolean] [default: false]
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--grpc-tls-cert TLS Certificate path for the [string]
gRPC (e.g.
"node1=/Users/username/node1-grpc.cert" with multiple nodes comma separated)
--grpc-tls-key TLS Certificate key path for [string]
the gRPC (e.g.
"node1=/Users/username/node1-grpc.key" with multiple nodes comma separated)
--grpc-web-endpoint Configure gRPC Web endpoint [Format: <address>[:<port>]] [string]
(Default port: 8080)
--grpc-web-tls-cert TLS Certificate path for gRPC [string]
Web (e.g.
"node1=/Users/username/node1-grpc-web.cert" with multiple nodes comma separated)
--grpc-web-tls-key TLC Certificate key path for [string]
gRPC Web (e.g.
"node1=/Users/username/node1-grpc-web.key" with multiple nodes comma separated)
--local-build-path path of hedera local repo [string]
--pvcs Enable persistent volume [boolean] [default: false]
claims to store data outside
the pod, required for
consensus node add
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-keys Generate gRPC TLS keys for [boolean] [default: false]
nodes
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-add execute
consensus dev-node-add execute
Executes the addition of a previously prepared node
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--admin-key Admin key [string] [default: "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"]
--app Testing app name [string] [default: "HederaNode.jar"]
--block-node-mapping Configure block-node priority [string]
mapping. Default: all
block-node included, first's
priority is 2. Unlisted
block-node will not routed to
the consensus node node.
Example: --block-node-mapping
1=2,2=1
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--envoy-ips IP mapping where key = value [string]
is node alias and static ip
for envoy proxy, (e.g.:
--envoy-ips
node1=127.0.0.1,node2=127.0.0.1)
--external-block-node-mapping Configure external-block-node [string]
priority mapping. Default: all
external-block-node included,
first's priority is 2.
Unlisted external-block-node
will not routed to the
consensus node node. Example:
--external-block-node-mapping
1=2,2=1
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-keys Generate gossip keys for nodes [boolean] [default: false]
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--grpc-tls-cert TLS Certificate path for the [string]
gRPC (e.g.
"node1=/Users/username/node1-grpc.cert" with multiple nodes comma separated)
--grpc-tls-key TLS Certificate key path for [string]
the gRPC (e.g.
"node1=/Users/username/node1-grpc.key" with multiple nodes comma separated)
--grpc-web-endpoint Configure gRPC Web endpoint [Format: <address>[:<port>]] [string]
(Default port: 8080)
--grpc-web-tls-cert TLS Certificate path for gRPC [string]
Web (e.g.
"node1=/Users/username/node1-grpc-web.cert" with multiple nodes comma separated)
--grpc-web-tls-key TLC Certificate key path for [string]
gRPC Web (e.g.
"node1=/Users/username/node1-grpc-web.key" with multiple nodes comma separated)
--haproxy-ips IP mapping where key = value [string]
is node alias and static ip
for haproxy, (e.g.:
--haproxy-ips
node1=127.0.0.1,node2=127.0.0.1)
--local-build-path path of hedera local repo [string]
--pvcs Enable persistent volume [boolean] [default: false]
claims to store data outside
the pod, required for
consensus node add
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-keys Generate gRPC TLS keys for [boolean] [default: false]
nodes
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-update
consensus dev-node-update
Dev operations for updating consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node update]
Commands:
consensus dev-node-update prepare Prepare the deployment to update a node with a specific version of Hedera platform
consensus dev-node-update submit-transactions Submit transactions for updating a node with a specific version of Hedera platform
consensus dev-node-update execute Executes the updating of a node with a specific version of Hedera platform
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus dev-node-update prepare
consensus dev-node-update prepare
Prepare the deployment to update a node with a specific version of Hedera platform
Options:
--node-alias Node alias (e.g. node99) [string] [required]
--output-dir Path to the directory where [string] [required]
the command context will be
saved to
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--gossip-private-key path and file name of the [string]
private key for signing gossip
in PEM key format to be used
--gossip-public-key path and file name of the [string]
public key for signing gossip
in PEM key format to be used
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--local-build-path path of hedera local repo [string]
--new-account-number new account number for node [string]
update transaction
--new-admin-key new admin key for the Hedera [string]
account
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-private-key path and file name of the [string]
private TLS key to be used
--tls-public-key path and file name of the [string]
public TLS key to be used
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-update submit-transactions
consensus dev-node-update submit-transactions
Submit transactions for updating a node with a specific version of Hedera platform
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--local-build-path path of hedera local repo [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-update execute
consensus dev-node-update execute
Executes the updating of a node with a specific version of Hedera platform
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--admin-key Admin key [string] [default: "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"]
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--gossip-endpoints Comma separated gossip [string]
endpoints of the node(e.g.
first one is internal, second
one is external)
--grpc-endpoints Comma separated gRPC endpoints [string]
of the node (at most 8)
--local-build-path path of hedera local repo [string]
--new-account-number new account number for node [string]
update transaction
--new-admin-key new admin key for the Hedera [string]
account
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
--wraps-key-path Path to a local directory [deprecated] [string]
containing pre-existing WRAPs
proving key files (.bin)
consensus dev-node-upgrade
consensus dev-node-upgrade
Dev operations for upgrading consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus network upgrade]
Commands:
consensus dev-node-upgrade prepare Prepare for upgrading network
consensus dev-node-upgrade submit-transactions Submit transactions for upgrading network
consensus dev-node-upgrade execute Executes the upgrading the network
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus dev-node-upgrade prepare
consensus dev-node-upgrade prepare
Prepare for upgrading network
Options:
--output-dir Path to the directory where [string] [required]
the command context will be
saved to
--api-permission-properties api-permission.properties file [string] [default: "templates/api-permission.properties"]
for node
--app Testing app name [string] [default: "HederaNode.jar"]
--application-env the application.env file for [string] [default: "templates/application.env"]
the node provides environment
variables to the
solo-container to be used when
the hedera platform is started
--application-properties application.properties file [string] [default: "templates/application.properties"]
for node (default merges with
Solo defaults; add comment
'SOLO_ENABLE_OVERWRITE=true'
in the file to use overwrite
mode)
--bootstrap-properties bootstrap.properties file for [string] [default: "templates/bootstrap.properties"]
node
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--freeze-block-drain-seconds Seconds to wait after [number] [default: 20]
consensus nodes reach
FREEZE_COMPLETE before
stopping them, allowing the
block stream to drain to the
block node
--local-build-path path of hedera local repo [string]
--log4j2-xml log4j2.xml file for node [string] [default: "templates/log4j2.xml"]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--settings-txt settings.txt file for node [string] [default: "templates/settings.txt"]
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-start Skip starting consensus nodes [boolean] [default: false]
after staging a freeze upgrade
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
--upgrade-version Version to be used for the [string]
upgrade
--upgrade-zip-file A zipped file used for network [string]
upgrade
-f, --values-file Comma separated chart values [string]
file paths for each cluster
(e.g.
values.yaml,cluster-1=./a/b/values1.yaml,cluster-2=./a/b/values2.yaml)
-v, --version Show version number [boolean]
consensus dev-node-upgrade submit-transactions
consensus dev-node-upgrade submit-transactions
Submit transactions for upgrading network
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--freeze-block-drain-seconds Seconds to wait after [number] [default: 20]
consensus nodes reach
FREEZE_COMPLETE before
stopping them, allowing the
block stream to drain to the
block node
--local-build-path path of hedera local repo [string]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-start Skip starting consensus nodes [boolean] [default: false]
after staging a freeze upgrade
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
--upgrade-version Version to be used for the [string]
upgrade
--upgrade-zip-file A zipped file used for network [string]
upgrade
-v, --version Show version number [boolean]
consensus dev-node-upgrade execute
consensus dev-node-upgrade execute
Executes the upgrading the network
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--api-permission-properties api-permission.properties file [string] [default: "templates/api-permission.properties"]
for node
--app Testing app name [string] [default: "HederaNode.jar"]
--application-env the application.env file for [string] [default: "templates/application.env"]
the node provides environment
variables to the
solo-container to be used when
the hedera platform is started
--application-properties application.properties file [string] [default: "templates/application.properties"]
for node (default merges with
Solo defaults; add comment
'SOLO_ENABLE_OVERWRITE=true'
in the file to use overwrite
mode)
--bootstrap-properties bootstrap.properties file for [string] [default: "templates/bootstrap.properties"]
node
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--freeze-block-drain-seconds Seconds to wait after [number] [default: 20]
consensus nodes reach
FREEZE_COMPLETE before
stopping them, allowing the
block stream to drain to the
block node
--local-build-path path of hedera local repo [string]
--log4j2-xml log4j2.xml file for node [string] [default: "templates/log4j2.xml"]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--settings-txt settings.txt file for node [string] [default: "templates/settings.txt"]
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-start Skip starting consensus nodes [boolean] [default: false]
after staging a freeze upgrade
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
--upgrade-version Version to be used for the [string]
upgrade
--upgrade-zip-file A zipped file used for network [string]
upgrade
-f, --values-file Comma separated chart values [string]
file paths for each cluster
(e.g.
values.yaml,cluster-1=./a/b/values1.yaml,cluster-2=./a/b/values2.yaml)
-v, --version Show version number [boolean]
consensus dev-node-delete
consensus dev-node-delete
Dev operations for delete consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus node destroy]
Commands:
consensus dev-node-delete prepare Prepares the deletion of a node with a specific version of Hedera platform
consensus dev-node-delete submit-transactions Submits transactions to the network nodes for deleting a node
consensus dev-node-delete execute Executes the deletion of a previously prepared node
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus dev-node-delete prepare
consensus dev-node-delete prepare
Prepares the deletion of a node with a specific version of Hedera platform
Options:
--node-alias Node alias (e.g. node99) [string] [required]
--output-dir Path to the directory where [string] [required]
the command context will be
saved to
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
consensus dev-node-delete submit-transactions
consensus dev-node-delete submit-transactions
Submits transactions to the network nodes for deleting a node
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--node-alias Node alias (e.g. node99) [string] [required]
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
consensus dev-node-delete execute
consensus dev-node-delete execute
Executes the deletion of a previously prepared node
Options:
--input-dir Path to the directory where [string] [required]
the command context will be
loaded from
--node-alias Node alias (e.g. node99) [string] [required]
--app Testing app name [string] [default: "HederaNode.jar"]
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-names Custom domain names for [string]
consensus nodes mapping for
the(e.g. node0=domain.name
where key is node alias and
value is domain name)with
multiple nodes comma separated
--endpoint-type Endpoint type (IP or FQDN) [string] [default: "FQDN"]
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gossip
endpoints published to the
network (Default port: 50111)
--local-build-path path of hedera local repo [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--service-endpoint-port Port used when building the [Format: <port> to apply the same port to every node, or <alias>=<port>[,<alias>=<port>] per node] [string]
consensus node gRPC service
endpoints published to the
network (Default port: 50211)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
consensus dev-freeze
consensus dev-freeze
Dev operations for freezing consensus nodes [DEPRECATED: since v0.94.0, removal v0.100.0, use consensus network freeze]
Commands:
consensus dev-freeze prepare-upgrade Prepare the network for a Freeze Upgrade operation
consensus dev-freeze freeze-upgrade Performs a Freeze Upgrade operation with on the network after it has been prepared with prepare-upgrade
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
consensus dev-freeze prepare-upgrade
consensus dev-freeze prepare-upgrade
Prepare the network for a Freeze Upgrade operation
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-alias The node alias to skip, [string]
because of a
NodeUpdateTransaction or it is
down (e.g. node99)
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
-v, --version Show version number [boolean]
consensus dev-freeze freeze-upgrade
consensus dev-freeze freeze-upgrade
Performs a Freeze Upgrade operation with on the network after it has been prepared with prepare-upgrade
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--simple-fees-schedules-file simpleFeesSchedules.json file [string]
applied to the network during
the upgrade; must match the
target version
--skip-node-alias The node alias to skip, [string]
because of a
NodeUpdateTransaction or it is
down (e.g. node99)
--throttles-file throttles.json file applied to [string]
the network during the
upgrade; must match the target
version
-v, --version Show version number [boolean]
deployment
deployment
Create, modify, and delete deployment configurations. Deployments are required for most of the other commands.
Commands:
deployment cluster View and manage Solo cluster references used by a deployment.
deployment config List, view, create, delete, and import deployments. These commands affect the local configuration only.
deployment state View the actual state of the deployment on the Kubernetes clusters or teardown/destroy all remote and local configuration for a given deployment.
deployment refresh [DEPRECATED] Use 'solo deployment port-forwards refresh' instead. Refresh port-forward processes for all components in the deployment.
deployment port-forwards Manage the port-forward processes for all components in the deployment.
deployment diagnostics Capture diagnostic information such as logs, signed states, and ledger/network/node configurations.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment cluster
deployment cluster
View and manage Solo cluster references used by a deployment.
Commands:
deployment cluster attach Attaches a cluster reference to a deployment.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment cluster attach
deployment cluster attach
Attaches a cluster reference to a deployment.
Options:
-c, --cluster-ref The cluster reference that [string] [required]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--dns-base-domain Base domain for the DNS is the [string] [default: "cluster.local"]
suffix used to construct the
fully qualified domain name
(FQDN)
--dns-consensus-node-pattern Pattern to construct the [string] [default: "network-{nodeAlias}-svc.{namespace}.svc"]
prefix for the fully qualified
domain name (FQDN) for the
consensus node, the suffix is
provided by the
--dns-base-domain option (ex.
network-{nodeAlias}-svc.{namespace}.svc)
--enable-cert-manager Pass the flag to enable cert [boolean] [default: false]
manager
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--num-consensus-nodes Used to specify desired number [number]
of consensus nodes for
pre-genesis deployments (an
additional cluster defaults to
0 in quiet mode)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment config
deployment config
List, view, create, delete, and import deployments. These commands affect the local configuration only.
Commands:
deployment config list Lists all local deployment configurations or deployments in a specific cluster.
deployment config create Creates a new local deployment configuration.
deployment config delete Removes a local deployment configuration.
deployment config info Displays the full status of a deployment including components, versions, and port-forward status.
deployment config ports List all port-forwards for a deployment. JSON and YAMl output formats, create files containing the data
deployment config import Imports a deployment into the local configuration from an existing cluster's remote config.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment config list
deployment config list
Lists all local deployment configurations or deployments in a specific cluster.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment config create
deployment config create
Creates a new local deployment configuration.
Options:
-d, --deployment The name the user will [string] [required]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
-n, --namespace Namespace [string] [required]
-l, --chain-id Chain ID [string] [default: "298"]
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--realm Realm number. Requires [number] [default: 0]
network-node > v61.0 for
non-zero values
--shard Shard number. Requires [number] [default: 0]
network-node > v61.0 for
non-zero values
-v, --version Show version number [boolean]
deployment config delete
deployment config delete
Removes a local deployment configuration.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment config info
deployment config info
Displays the full status of a deployment including components, versions, and port-forward status.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment config ports
deployment config ports
List all port-forwards for a deployment. JSON and YAMl output formats, create files containing the data
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-o, --output Output format. One of: "json", [string]
"yaml", "wide"
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment config import
deployment config import
Imports a deployment into the local configuration from an existing cluster's remote config.
Options:
--context The Kubernetes context name to [string]
be used
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-n, --namespace Namespace [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment state
deployment state
View the actual state of the deployment on the Kubernetes clusters or teardown/destroy all remote and local configuration for a given deployment.
Commands:
deployment state images Lists every pod in the deployment namespace and shows its running container image. Useful to verify that a locally-built image was loaded correctly.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment state images
deployment state images
Lists every pod in the deployment namespace and shows its running container image. Useful to verify that a locally-built image was loaded correctly.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment refresh
deployment refresh
[DEPRECATED] Use 'solo deployment port-forwards refresh' instead. Refresh port-forward processes for all components in the deployment.
Commands:
deployment refresh port-forwards [DEPRECATED] Use 'solo deployment port-forwards refresh' instead. Refresh and restore killed port-forward processes.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment refresh port-forwards
deployment refresh port-forwards
[DEPRECATED] Use 'solo deployment port-forwards refresh' instead. Refresh and restore killed port-forward processes.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment port-forwards
deployment port-forwards
Manage the port-forward processes for all components in the deployment.
Commands:
deployment port-forwards refresh Refresh and restore killed port-forward processes.
deployment port-forwards stop Stop (close down) all port-forwards for a deployment and remove them from the remote config.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment port-forwards refresh
deployment port-forwards refresh
Refresh and restore killed port-forward processes.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment port-forwards stop
deployment port-forwards stop
Stop (close down) all port-forwards for a deployment and remove them from the remote config.
Options:
-d, --deployment The name the user will [string] [required]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics
deployment diagnostics
Capture diagnostic information such as logs, signed states, and ledger/network/node configurations.
Commands:
deployment diagnostics all Captures logs, configs, and diagnostics artifacts for all deployments by default, or only the selected deployment when --deployment is provided.
deployment diagnostics debug Same scope as diagnostics all, but creates a zip archive for easy sharing.
deployment diagnostics connections Tests connections to Consensus, Relay, Explorer, Mirror and Block nodes for all deployments by default, or only the selected deployment when --deployment is provided.
deployment diagnostics logs Gets logs and configuration files for all deployments by default, or only the selected deployment when --deployment is provided.
deployment diagnostics analyze Analyze a previously collected diagnostics logs directory for common failure signatures.
deployment diagnostics report Collects diagnostics (scoped by --deployment when provided) and creates a GitHub issue using the gh CLI.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
deployment diagnostics all
deployment diagnostics all
Captures logs, configs, and diagnostics artifacts for all deployments by default, or only the selected deployment when --deployment is provided.
Options:
--check Fail if any configured remote [boolean] [default: false]
port-forward is not reachable
locally
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics debug
deployment diagnostics debug
Same scope as diagnostics all, but creates a zip archive for easy sharing.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--output-dir Path to the directory where [string]
the command context will be
saved to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics connections
deployment diagnostics connections
Tests connections to Consensus, Relay, Explorer, Mirror and Block nodes for all deployments by default, or only the selected deployment when --deployment is provided.
Options:
--check Fail if any configured remote [boolean] [default: false]
port-forward is not reachable
locally
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics logs
deployment diagnostics logs
Gets logs and configuration files for all deployments by default, or only the selected deployment when --deployment is provided.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--output-dir Path to the directory where [string]
the command context will be
saved to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics analyze
deployment diagnostics analyze
Analyze a previously collected diagnostics logs directory for common failure signatures.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--input-dir Path to the directory where [string]
the command context will be
loaded from
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
deployment diagnostics report
deployment diagnostics report
Collects diagnostics (scoped by --deployment when provided) and creates a GitHub issue using the gh CLI.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--output-dir Path to the directory where [string]
the command context will be
saved to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
explorer
explorer
Explorer Node operations for creating, modifying, and destroying resources.These commands require the presence of an existing deployment.
Commands:
explorer node List, create, manage, or destroy explorer node instances. Operates on a single explorer node instance at a time.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
explorer node
explorer node
List, create, manage, or destroy explorer node instances. Operates on a single explorer node instance at a time.
Commands:
explorer node add Adds and configures a new node instance.
explorer node destroy Deletes the specified node from the deployment.
explorer node upgrade Upgrades the specified node in the deployment.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
explorer node add
explorer node add
Adds and configures a new node instance.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
-s, --cluster-setup-namespace Cluster Setup Namespace [string] [default: "solo-setup"]
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--enable-explorer-tls Enable Explorer TLS, defaults [boolean] [default: false]
to false, requires certManager
and certManagerCrds, which can
be deployed through
solo-cluster-setup chart or
standalone
--enable-ingress enable ingress on the [boolean] [default: false]
component/pod
--explorer-chart-dir Explorer local chart directory [string]
path (e.g.
~/hiero-mirror-node-explorer/_frontend/chart)
--explorer-static-ip The static IP address to use [string]
for the Explorer load
balancer, defaults to ""
--explorer-tls-host-name The host name to use for the [string] [default: "explorer.solo.local"]
Explorer TLS, defaults to
"explorer.solo.local"
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--ingress-controller-value-file The value file to use for [string]
ingress controller, defaults
to ""
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--mirror-namespace Namespace to use for the [string]
Mirror Node deployment, a new
one will be created if it does
not exist
--mirror-node-id The id of the mirror node [number]
which to connect
-n, --namespace Namespace [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-cluster-issuer-type The TLS cluster issuer type to [string] [default: "self-signed"]
use for hedera explorer,
defaults to "self-signed", the
available options are:
"acme-staging", "acme-prod",
or "self-signed"
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
explorer node destroy
explorer node destroy
Deletes the specified node from the deployment.
Options:
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
explorer node upgrade
explorer node upgrade
Upgrades the specified node in the deployment.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
-s, --cluster-setup-namespace Cluster Setup Namespace [string] [default: "solo-setup"]
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--enable-explorer-tls Enable Explorer TLS, defaults [boolean] [default: false]
to false, requires certManager
and certManagerCrds, which can
be deployed through
solo-cluster-setup chart or
standalone
--enable-ingress enable ingress on the [boolean] [default: false]
component/pod
--explorer-chart-dir Explorer local chart directory [string]
path (e.g.
~/hiero-mirror-node-explorer/_frontend/chart)
--explorer-static-ip The static IP address to use [string]
for the Explorer load
balancer, defaults to ""
--explorer-tls-host-name The host name to use for the [string] [default: "explorer.solo.local"]
Explorer TLS, defaults to
"explorer.solo.local"
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
--ingress-controller-value-file The value file to use for [string]
ingress controller, defaults
to ""
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--mirror-namespace Namespace to use for the [string]
Mirror Node deployment, a new
one will be created if it does
not exist
--mirror-node-id The id of the mirror node [number]
which to connect
-n, --namespace Namespace [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--tls-cluster-issuer-type The TLS cluster issuer type to [string] [default: "self-signed"]
use for hedera explorer,
defaults to "self-signed", the
available options are:
"acme-staging", "acme-prod",
or "self-signed"
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
init
init
Initialize local environment [DEPRECATED: since v0.85.0, removal v0.91.0]
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
keys
keys
Consensus key generation operations
Commands:
keys consensus Generate unique cryptographic keys (gossip or grpc TLS keys) for the Consensus Node instances.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
keys consensus
keys consensus
Generate unique cryptographic keys (gossip or grpc TLS keys) for the Consensus Node instances.
Commands:
keys consensus generate Generates TLS keys required for consensus node communication.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
keys consensus generate
keys consensus generate
Generates TLS keys required for consensus node communication.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--gossip-keys Generate gossip keys for nodes [boolean] [default: false]
-n, --namespace Namespace [string]
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--tls-keys Generate gRPC TLS keys for [boolean] [default: false]
nodes
-v, --version Show version number [boolean]
ledger
ledger
System, Account, and Crypto ledger-based management operations. These commands require an operational set of consensus nodes and may require an operational mirror node.
Commands:
ledger system Perform a full ledger initialization on a new deployment, rekey privileged/system accounts, or setup network staking parameters.
ledger account View, list, create, update, delete, and import ledger accounts.
ledger file Upload or update files on the Hiero network.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
ledger system
ledger system
Perform a full ledger initialization on a new deployment, rekey privileged/system accounts, or setup network staking parameters.
Commands:
ledger system init Re-keys ledger system accounts and consensus node admin keys with uniquely generated ED25519 private keys and will stake consensus nodes.
ledger system reset Resets the ledger system to genesis by clearing saved states and ledger-related secrets.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
ledger system init
ledger system init
Re-keys ledger system accounts and consensus node admin keys with uniquely generated ED25519 private keys and will stake consensus nodes.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-v, --version Show version number [boolean]
ledger system reset
ledger system reset
Resets the ledger system to genesis by clearing saved states and ledger-related secrets.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-v, --version Show version number [boolean]
ledger account
ledger account
View, list, create, update, delete, and import ledger accounts.
Commands:
ledger account update Updates an existing ledger account.
ledger account create Creates a new ledger account.
ledger account info Gets the account info including the current amount of HBAR
ledger account predefined Creates predefined accounts used by one-shot deployments.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
ledger account update
ledger account update
Updates an existing ledger account.
Options:
--account-id The Hedera account id, e.g.: [string] [required]
0.0.1001
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--ecdsa-private-key Specify a hex-encoded ECDSA [string]
private key for the Hedera
account
--ed25519-private-key Specify a hex-encoded ED25519 [string]
private key for the Hedera
account
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--hbar-amount Amount of HBAR to add [number] [default: 100]
-v, --version Show version number [boolean]
ledger account create
ledger account create
Creates a new ledger account.
Options:
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--create-amount Amount of new account to [number] [default: 1]
create
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--ecdsa-private-key Specify a hex-encoded ECDSA [string]
private key for the Hedera
account
--ed25519-private-key Specify a hex-encoded ED25519 [string]
private key for the Hedera
account
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--generate-ecdsa-key Generate ECDSA private key for [boolean] [default: false]
the Hedera account
--hbar-amount Amount of HBAR to add [number] [default: 100]
--private-key Show private key information [boolean] [default: false]
--set-alias Sets the alias for the Hedera [boolean] [default: false]
account when it is created,
requires --ecdsa-private-key
-v, --version Show version number [boolean]
ledger account info
ledger account info
Gets the account info including the current amount of HBAR
Options:
--account-id The Hedera account id, e.g.: [string] [required]
0.0.1001
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--private-key Show private key information [boolean] [default: false]
-v, --version Show version number [boolean]
ledger account predefined
ledger account predefined
Creates predefined accounts used by one-shot deployments.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
ledger file
ledger file
Upload or update files on the Hiero network.
Commands:
ledger file create Create a new file on the Hiero network
ledger file update Update an existing file on the Hiero network
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
ledger file create
ledger file create
Create a new file on the Hiero network
Options:
--file-path Local path to the file to [string] [required]
upload
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
ledger file update
ledger file update
Update an existing file on the Hiero network
Options:
--file-id The network file id, e.g.: [string] [required]
0.0.150
--file-path Local path to the file to [string] [required]
upload
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
mirror
mirror
Mirror Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
Commands:
mirror node List, create, manage, or destroy mirror node instances. Operates on a single mirror node instance at a time.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
mirror node
mirror node
List, create, manage, or destroy mirror node instances. Operates on a single mirror node instance at a time.
Commands:
mirror node add Adds and configures a new node instance.
mirror node destroy Deletes the specified node from the deployment.
mirror node upgrade Upgrades the specified node from the deployment.
mirror node collect-jfr Downloads the Java Flight Recorder recording from a mirror node importer instance in the specified deployment to the local solo logs directory. Requires the mirror node to have been deployed with Java Flight Recorder enabled.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
mirror node add
mirror node add
Adds and configures a new node instance.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev [boolean] [default: false]
Enable debug mode
--debug-mirror-node-component Open the default jvm debug [string]
port (5005) on the given
mirror node component and
port-forward it to localhost.
Allowed values: importer
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--enable-ingress enable ingress on the [boolean] [default: false]
component/pod
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--external-database-host Use to provide the external [string]
database host if the '
--use-external-database ' is
passed
--external-database-owner-password Use to provide the external [string]
database owner's password if
the ' --use-external-database
' is passed
--external-database-owner-username Use to provide the external [string]
database owner's username if
the ' --use-external-database
' is passed
--external-database-read-password Use to provide the external [string]
database readonly user's
password if the '
--use-external-database ' is
passed
--external-database-read-username Use to provide the external [string]
database readonly user's
username if the '
--use-external-database ' is
passed
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--ingress-controller-value-file The value file to use for [string]
ingress controller, defaults
to ""
--mirror-node-chart-dir Mirror node local chart [string]
directory path (e.g.
~/hiero-mirror-node/charts).
NOTE: This only provides the
Helm chart templates — it does
NOT make the chart images
available to the cluster. All
container images referenced by
the chart must already be
pullable (e.g. published to a
registry or loaded into the
cluster with `kind load
docker-image`). Using a local
branch chart with SNAPSHOT
image tags will cause pods to
fail with ImagePullBackOff
unless those images have been
built and pushed to a registry
or loaded into the cluster.
--mirror-node-source Where the mirror node imports [string] [default: "auto"]
its data from: "bucket" reads
the consensus node record
files, "block-node" reads the
block stream of a block node
and fails when no block node
applies, "auto" picks the
block node when one is
deployed in the same cluster
and the bucket otherwise. Pass
it again on every upgrade,
because "auto" is applied when
it is omitted
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
--mirror-static-ip static IP address for the [string]
mirror node
--operator-id Operator ID [string]
--operator-key Operator Key [string]
--parallel-deploy Run independent one-shot [boolean] [default: true]
deploy stages in parallel
(consensus+block,
mirror+accounts,
explorer+relay). Disable with
--no-parallel-deploy for
sequential execution (useful
for debugging or
resource-constrained
environments).
--pinger Enable Pinger service in the [boolean] [default: false]
Mirror node monitor
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--storage-bucket name of storage bucket for [string]
mirror node importer
--storage-bucket-prefix path prefix of storage bucket [string]
mirror node importer
--storage-bucket-region region of storage bucket [string]
mirror node importer
--storage-endpoint storage endpoint URL for [string]
mirror node importer
--storage-read-access-key storage read access key for [string]
mirror node importer
--storage-read-secrets storage read-secret key for [string]
mirror node importer
--storage-type storage type for saving stream [default: "minio_only"]
files, available options are
minio_only, aws_only,
gcs_only, aws_and_gcs
--use-external-database Set to true if you have an [boolean] [default: false]
external database to use
instead of the database that
the Mirror Node Helm chart
supplies
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
mirror node destroy
mirror node destroy
Deletes the specified node from the deployment.
Options:
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
mirror node upgrade
mirror node upgrade
Upgrades the specified node from the deployment.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev [boolean] [default: false]
Enable debug mode
--debug-mirror-node-component Open the default jvm debug [string]
port (5005) on the given
mirror node component and
port-forward it to localhost.
Allowed values: importer
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--enable-ingress enable ingress on the [boolean] [default: false]
component/pod
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--external-database-host Use to provide the external [string]
database host if the '
--use-external-database ' is
passed
--external-database-owner-password Use to provide the external [string]
database owner's password if
the ' --use-external-database
' is passed
--external-database-owner-username Use to provide the external [string]
database owner's username if
the ' --use-external-database
' is passed
--external-database-read-password Use to provide the external [string]
database readonly user's
password if the '
--use-external-database ' is
passed
--external-database-read-username Use to provide the external [string]
database readonly user's
username if the '
--use-external-database ' is
passed
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
--ingress-controller-value-file The value file to use for [string]
ingress controller, defaults
to ""
--mirror-node-chart-dir Mirror node local chart [string]
directory path (e.g.
~/hiero-mirror-node/charts).
NOTE: This only provides the
Helm chart templates — it does
NOT make the chart images
available to the cluster. All
container images referenced by
the chart must already be
pullable (e.g. published to a
registry or loaded into the
cluster with `kind load
docker-image`). Using a local
branch chart with SNAPSHOT
image tags will cause pods to
fail with ImagePullBackOff
unless those images have been
built and pushed to a registry
or loaded into the cluster.
--mirror-node-source Where the mirror node imports [string] [default: "auto"]
its data from: "bucket" reads
the consensus node record
files, "block-node" reads the
block stream of a block node
and fails when no block node
applies, "auto" picks the
block node when one is
deployed in the same cluster
and the bucket otherwise. Pass
it again on every upgrade,
because "auto" is applied when
it is omitted
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
--mirror-static-ip static IP address for the [string]
mirror node
--operator-id Operator ID [string]
--operator-key Operator Key [string]
--pinger Enable Pinger service in the [boolean] [default: false]
Mirror node monitor
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
--storage-bucket name of storage bucket for [string]
mirror node importer
--storage-bucket-prefix path prefix of storage bucket [string]
mirror node importer
--storage-bucket-region region of storage bucket [string]
mirror node importer
--storage-endpoint storage endpoint URL for [string]
mirror node importer
--storage-read-access-key storage read access key for [string]
mirror node importer
--storage-read-secrets storage read-secret key for [string]
mirror node importer
--storage-type storage type for saving stream [default: "minio_only"]
files, available options are
minio_only, aws_only,
gcs_only, aws_and_gcs
--use-external-database Set to true if you have an [boolean] [default: false]
external database to use
instead of the database that
the Mirror Node Helm chart
supplies
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
mirror node collect-jfr
mirror node collect-jfr
Downloads the Java Flight Recorder recording from a mirror node importer instance in the specified deployment to the local solo logs directory. Requires the mirror node to have been deployed with Java Flight Recorder enabled.
Options:
-d, --deployment The name the user will [string] [required]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
relay
relay
RPC Relay Node operations for creating, modifying, and destroying resources. These commands require the presence of an existing deployment.
Commands:
relay node List, create, manage, or destroy relay node instances. Operates on a single relay node instance at a time.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
relay node
relay node
List, create, manage, or destroy relay node instances. Operates on a single relay node instance at a time.
Commands:
relay node add Adds and configures a new node instance.
relay node destroy Deletes the specified node from the deployment.
relay node upgrade Upgrades the specified node from the deployment.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
relay node add
relay node add
Adds and configures a new node instance.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--mirror-namespace Namespace to use for the [string]
Mirror Node deployment, a new
one will be created if it does
not exist
--mirror-node-id The id of the mirror node [number]
which to connect
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
--operator-id Operator ID [string]
--operator-key Operator Key [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-chart-dir Relay local chart directory [string]
path (e.g.
~/hiero-json-rpc-relay/charts)
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
--replica-count Replica count [number] [default: 1]
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
relay node destroy
relay node destroy
Deletes the specified node from the deployment.
Options:
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
relay node upgrade
relay node upgrade
Upgrades the specified node from the deployment.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-l, --chain-id Chain ID [string] [default: "298"]
--chart-dir Local chart directory path [string]
(e.g. ~/solo-charts/charts)
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--component-image , --relay-image Docker [string]
image override. Supports a
published registry reference
(e.g.
ghcr.io/hiero-ledger/component:1.2.3), a locally built image (e.g. component:1.2.3), or a Kind-attached local registry (e.g. localhost:5001/component:1.2.3). Locally available images are loaded into every target Kind cluster and use pullPolicy: Never. For non-Kind targets, publish the image to a registry reachable by the cluster. Some multi-module components treat the value as a repository prefix and derive and load each module image from it.
--component-image-archive Path to a docker save image [string]
archive. Requires
--component-image to identify
the archived image. The
archive is loaded into every
target Kind cluster and uses
pullPolicy: Never.
--debug , --dev , --dev [boolean] [default: false]
Enable debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--domain-name Custom domain name [string]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--id The numeric identifier for the [number]
component
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--mirror-namespace Namespace to use for the [string]
Mirror Node deployment, a new
one will be created if it does
not exist
--mirror-node-id The id of the mirror node [number]
which to connect
-i, --node-aliases Comma separated node aliases [string]
(empty means all nodes)
--operator-id Operator ID [string]
--operator-key Operator Key [string]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-chart-dir Relay local chart directory [string]
path (e.g.
~/hiero-json-rpc-relay/charts)
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
--replica-count Replica count [number] [default: 1]
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
cache
cache
Manage solo cached items.
Commands:
cache image Manage image archives used by solo.
cache chart Manage helm chart archives used by solo.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cache image
cache image
Manage image archives used by solo.
Commands:
cache image pull Pull and caches docker images used by solo, prerequisite for `solo cache image load`.
cache image load Loads the images archive into a cluster. Pulling the images with `solo cache images pull` is a prerequisite.
cache image list Lists all cached image archives.
cache image clear Clears the image archives.
cache image prune Prune the image archives.
cache image status Lists all images, displays data about them and all missing images.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cache image pull
cache image pull
Pull and caches docker images used by solo, prerequisite for `solo cache image load`.
Options:
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--edge Use edge component versions [boolean] [default: false]
(newer than defaults). Also
supports version overrides
from solo.config.yaml and
solo.config.json, for example:
`consensus-node-version:
v0.73.0` (YAML) or
`{"consensusNodeVersion":"v0.73.0"}` (JSON).
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
-v, --version Show version number [boolean]
cache image load
cache image load
Loads the images archive into a cluster. Pulling the images with `solo cache images pull` is a prerequisite.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache image list
cache image list
Lists all cached image archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache image clear
cache image clear
Clears the image archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache image prune
cache image prune
Prune the image archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache image status
cache image status
Lists all images, displays data about them and all missing images.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache chart
cache chart
Manage helm chart archives used by solo.
Commands:
cache chart pull Pulls and caches the helm charts used by solo so deploys can install them from the local cache.
cache chart list Lists all cached helm chart archives.
cache chart clear Clears the cached helm chart archives.
cache chart prune Prunes the cached helm chart archives.
cache chart status Lists all cached helm charts, their total size, and any missing chart archives.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
cache chart pull
cache chart pull
Pulls and caches the helm charts used by solo so deploys can install them from the local cache.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache chart list
cache chart list
Lists all cached helm chart archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache chart clear
cache chart clear
Clears the cached helm chart archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache chart prune
cache chart prune
Prunes the cached helm chart archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
cache chart status
cache chart status
Lists all cached helm charts, their total size, and any missing chart archives.
Options:
--cache-dir Local cache directory [string] [default: "/home/runner/.solo/cache"]
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
one-shot
one-shot
One Shot commands for new and returning users who need a preset environment type. These commands use reasonable defaults to provide a single command out of box experience.
Commands:
one-shot single Creates a uniquely named deployment with a single consensus node, mirror node, block node, relay node, and explorer node.
one-shot multi Creates a uniquely named deployment with multiple consensus nodes, mirror node, block node, relay node, and explorer node.
one-shot falcon Creates a uniquely named deployment with optional chart values override using --values-file.
one-shot show Display information about one-shot deployments.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
one-shot single
one-shot single
Creates a uniquely named deployment with a single consensus node, mirror node, block node, relay node, and explorer node.
Commands:
one-shot single deploy Deploys all required components for the selected one shot configuration.
one-shot single destroy Removes the deployed resources for the selected one shot configuration.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
one-shot single deploy
one-shot single deploy
Deploys all required components for the selected one shot configuration.
Options:
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
-l, --chain-id Chain ID [string] [default: "298"]
--chart-version Block node chart version [deprecated] [string] [default: "0.44.3"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--edge Use edge component versions [boolean] [default: false]
(newer than defaults). Also
supports version overrides
from solo.config.yaml and
solo.config.json, for example:
`consensus-node-version:
v0.73.0` (YAML) or
`{"consensusNodeVersion":"v0.73.0"}` (JSON).
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--metrics-server Deploy metrics server to [boolean] [default: false]
enable kubectl top for CPU and
memory usage monitoring
--minimal-setup Create a deployment with [boolean] [default: false]
minimal setup. Only includes
the consensus node(s) and
mirror node, without the
JSON-RPC relay or explorer
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
-n, --namespace Namespace [string]
--parallel-deploy Run independent one-shot [boolean] [default: true]
deploy stages in parallel
(consensus+block,
mirror+accounts,
explorer+relay). Disable with
--no-parallel-deploy for
sequential execution (useful
for debugging or
resource-constrained
environments).
--pinger Enable Pinger service in the [boolean] [default: false]
Mirror node monitor
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
--rollback Opt in to automatic cleanup [boolean] [default: false]
when deploy fails. By default,
failed one-shot deploys keep
partial resources so you can
inspect the failure and re-run
the same command.
-v, --version Show version number [boolean]
one-shot single destroy
one-shot single destroy
Removes the deployed resources for the selected one shot configuration.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
one-shot multi
one-shot multi
Creates a uniquely named deployment with multiple consensus nodes, mirror node, block node, relay node, and explorer node.
Commands:
one-shot multi deploy Deploys all required components for the selected multiple node one shot configuration.
one-shot multi destroy Removes the deployed resources for the selected multiple node one shot configuration.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
one-shot multi deploy
one-shot multi deploy
Deploys all required components for the selected multiple node one shot configuration.
Options:
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
-l, --chain-id Chain ID [string] [default: "298"]
--chart-version Block node chart version [deprecated] [string] [default: "0.44.3"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--edge Use edge component versions [boolean] [default: false]
(newer than defaults). Also
supports version overrides
from solo.config.yaml and
solo.config.json, for example:
`consensus-node-version:
v0.73.0` (YAML) or
`{"consensusNodeVersion":"v0.73.0"}` (JSON).
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--metrics-server Deploy metrics server to [boolean] [default: false]
enable kubectl top for CPU and
memory usage monitoring
--minimal-setup Create a deployment with [boolean] [default: false]
minimal setup. Only includes
the consensus node(s) and
mirror node, without the
JSON-RPC relay or explorer
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
-n, --namespace Namespace [string]
--num-consensus-nodes Used to specify desired number [number]
of consensus nodes for
pre-genesis deployments (an
additional cluster defaults to
0 in quiet mode)
--parallel-deploy Run independent one-shot [boolean] [default: true]
deploy stages in parallel
(consensus+block,
mirror+accounts,
explorer+relay). Disable with
--no-parallel-deploy for
sequential execution (useful
for debugging or
resource-constrained
environments).
--pinger Enable Pinger service in the [boolean] [default: false]
Mirror node monitor
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
--rollback Opt in to automatic cleanup [boolean] [default: false]
when deploy fails. By default,
failed one-shot deploys keep
partial resources so you can
inspect the failure and re-run
the same command.
-v, --version Show version number [boolean]
one-shot multi destroy
one-shot multi destroy
Removes the deployed resources for the selected multiple node one shot configuration.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
one-shot falcon
one-shot falcon
Creates a uniquely named deployment with optional chart values override using --values-file.
Commands:
one-shot falcon deploy Deploys all required components for the selected one shot configuration. The values file is optional; without one, the one-shot single defaults are used.
one-shot falcon destroy Removes the deployed resources for the selected one shot configuration (with optional values file).
one-shot falcon prepare Generates a falcon values file for use with one-shot falcon deploy. Writes to /home/runner/.solo/cache/falcon-values.yaml by default.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
one-shot falcon deploy
one-shot falcon deploy
Deploys all required components for the selected one shot configuration. The values file is optional; without one, the one-shot single defaults are used.
Options:
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
--chart-version Block node chart version [deprecated] [string] [default: "0.44.3"]
-c, --cluster-ref The cluster reference that [string]
will be used for referencing
the Kubernetes cluster and
stored in the local and remote
configuration for the
deployment. For commands that
take multiple clusters they
can be separated by commas.
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev Enable [boolean] [default: false]
debug mode
--deploy-explorer Deploy explorer as part of [boolean] [default: true]
one-shot falcon deployment
--deploy-mirror-node Deploy mirror node as part of [boolean] [default: true]
one-shot falcon deployment
--deploy-relay Deploy relay as part of [boolean] [default: true]
one-shot falcon deployment
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--edge Use edge component versions [boolean] [default: false]
(newer than defaults). Also
supports version overrides
from solo.config.yaml and
solo.config.json, for example:
`consensus-node-version:
v0.73.0` (YAML) or
`{"consensusNodeVersion":"v0.73.0"}` (JSON).
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--external-address Bind address for kubectl [string]
port-forward (for example
127.0.0.1 or 0.0.0.0)
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--metrics-server Deploy metrics server to [boolean] [default: false]
enable kubectl top for CPU and
memory usage monitoring
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
-n, --namespace Namespace [string]
--num-consensus-nodes Used to specify desired number [number]
of consensus nodes for
pre-genesis deployments (an
additional cluster defaults to
0 in quiet mode)
--parallel-deploy Run independent one-shot [boolean] [default: true]
deploy stages in parallel
(consensus+block,
mirror+accounts,
explorer+relay). Disable with
--no-parallel-deploy for
sequential execution (useful
for debugging or
resource-constrained
environments).
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
--rollback Opt in to automatic cleanup [boolean] [default: false]
when deploy fails. By default,
failed one-shot deploys keep
partial resources so you can
inspect the failure and re-run
the same command.
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
one-shot falcon destroy
one-shot falcon destroy
Removes the deployed resources for the selected one shot configuration (with optional values file).
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
one-shot falcon prepare
one-shot falcon prepare
Generates a falcon values file for use with one-shot falcon deploy. Writes to /home/runner/.solo/cache/falcon-values.yaml by default.
Options:
--block-node-version Block node version to deploy [string]
for (e.g. v0.31.0 or 0.31.0).
--chart-version Block node chart version [deprecated] [string] [default: "0.44.3"]
--consensus-node-version Consensus node version to [string]
deploy (e.g. v0.73.0 or
0.73.0).
--debug , --dev Enable [boolean] [default: false]
debug mode
--debug-node-alias Enable default jvm debug port [string]
(5005) for the given node id
--explorer-version Explorer chart version [string] [default: "26.2.0"]
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--load-balancer Expose the deployed services [boolean] [default: false]
via a LoadBalancer service
type
--local-build-path path of hedera local repo [string]
--mirror-node-version Mirror node chart version [string] [default: "v0.164.2"]
--num-consensus-nodes Used to specify desired number [number]
of consensus nodes for
pre-genesis deployments (an
additional cluster defaults to
0 in quiet mode)
--output-values-file Output path for the generated [string] [default: "/home/runner/.solo/cache/falcon-values.yaml"]
falcon values YAML file.
Defaults to
~/.solo/cache/falcon-values.yaml. Relative paths are resolved against the current working directory.
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
--relay-release Relay release tag (e.g. [deprecated] [string] [default: "0.81.0"]
v0.48.0)
--relay-version JSON-RPC relay version to [string]
deploy (e.g. v0.76.2 or
0.76.2).
-t, --release-tag Consensus node release tag [deprecated] [string] [default: "v0.78.1"]
(e.g. v0.78.1)
--solo-chart-version Solo testing chart version [string] [default: "0.67.0"]
-v, --version Show version number [boolean]
one-shot show
one-shot show
Display information about one-shot deployments.
Commands:
one-shot show deployment Display information about the last one-shot deployment including name, versions, and deployed components.
one-shot show accounts Display the contents of the one-shot deployment accounts.json file (supports --output json|yaml|wide).
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
one-shot show deployment
one-shot show deployment
Display information about the last one-shot deployment including name, versions, and deployed components.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
one-shot show accounts
one-shot show accounts
Display the contents of the one-shot deployment accounts.json file (supports --output json|yaml|wide).
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-o, --output Output format. One of: "json", [string]
"yaml", "wide"
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
rapid-fire
rapid-fire
Commands for performing load tests a Solo deployment
Commands:
rapid-fire load Run load tests using the network load generator with the selected class.
rapid-fire destroy Uninstall the Network Load Generator Helm chart and clean up resources.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
rapid-fire load
rapid-fire load
Run load tests using the network load generator with the selected class.
Commands:
rapid-fire load start Start a rapid-fire load test using the selected class.
rapid-fire load stop Stop any running processes using the selected class.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
rapid-fire load start
rapid-fire load start
Start a rapid-fire load test using the selected class.
Options:
--args All arguments to be passed to [string] [required]
the NLG load test class. Value
MUST be wrapped in 2 sets of
different quotes. Example:
'"-c 100 -a 40 -t 3600"'
--test The class name of the [string] [required]
Performance Test to run
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--javaHeap Max Java heap size in GB for [number] [default: 8]
the NLG load test class,
defaults to 8
--max-rtt Maximum allowed end-to-end [number] [default: 0]
round-trip time in
milliseconds, from transaction
submission to mirror node
availability
--max-tps The maximum transactions per [number] [default: 0]
second to be generated by the
NLG load test
--min-tps Minimum acceptable [number] [default: 0]
transactions per second
achieved by the NLG load test;
0 disables the check
--mirror-namespace Namespace to use for the [string]
Mirror Node deployment, a new
one will be created if it does
not exist
--package The package name of the [string] [default: "com.hedera.benchmark"]
Performance Test to run.
Defaults to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-f, --values-file Comma separated chart values [string]
files, each in YAML or JSON
format
-v, --version Show version number [boolean]
rapid-fire load stop
rapid-fire load stop
Stop any running processes using the selected class.
Options:
--test The class name of the [string] [required]
Performance Test to run
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
--package The package name of the [string] [default: "com.hedera.benchmark"]
Performance Test to run.
Defaults to
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
rapid-fire destroy
rapid-fire destroy
Uninstall the Network Load Generator Helm chart and clean up resources.
Commands:
rapid-fire destroy all Uninstall the Network Load Generator Helm chart and remove all related resources.
Options:
--debug , --dev Enable debug [boolean] [default: false]
mode
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-v, --version Show version number [boolean]
rapid-fire destroy all
rapid-fire destroy all
Uninstall the Network Load Generator Helm chart and remove all related resources.
Options:
--debug , --dev , --dev Enable [boolean] [default: false]
debug mode
-d, --deployment The name the user will [string]
reference locally to link to a
deployment. Falls back to the
SOLO_DEPLOYMENT environment
variable, or is selected
automatically when the local
configuration contains exactly
one deployment
--force Force actions even if those [boolean] [default: false]
can be skipped
--force-port-forward Force port forward to access [boolean] [default: true]
the network services
-q, --quiet-mode Quiet mode, do not prompt for [boolean] [default: false]
confirmation
-v, --version Show version number [boolean]
2.9.2 - CLI Migration Reference
Overview
Use this page when migrating scripts or runbooks from legacy Solo CLI command paths (< v0.44.0) to the current command structure.
For full current syntax and flags, see Solo CLI Reference.
Legacy to Current Mapping
| Legacy command | Current command |
|---|---|
block node add | block node add |
block node destroy | block node destroy |
block node upgrade | block node upgrade |
account init | ledger system init |
account update | ledger account update |
account create | ledger account create |
account get | ledger account info |
quick-start single deploy | one-shot single deploy |
quick-start single destroy | one-shot single destroy |
cluster-ref connect | cluster-ref config connect |
cluster-ref disconnect | cluster-ref config disconnect |
cluster-ref list | cluster-ref config list |
cluster-ref info | cluster-ref config info |
cluster-ref setup | cluster-ref config setup |
cluster-ref reset | cluster-ref config reset |
deployment add-cluster | deployment cluster attach |
deployment list | deployment config list |
deployment create | deployment config create |
deployment delete | deployment config delete |
explorer deploy | explorer node add |
explorer destroy | explorer node destroy |
mirror-node deploy | mirror node add |
mirror-node destroy | mirror node destroy |
relay deploy | relay node add |
relay destroy | relay node destroy |
network deploy | consensus network deploy |
network destroy | consensus network destroy |
node keys | keys consensus generate |
node freeze | consensus network freeze |
node upgrade | consensus network upgrade |
node setup | consensus node setup |
node start | consensus node start |
node stop | consensus node stop |
node restart | consensus node restart |
node refresh | consensus node refresh |
node add | consensus node add |
node update | consensus node update |
node delete | consensus node destroy |
node add-prepare | consensus dev-node-add prepare |
node add-submit-transaction | consensus dev-node-add submit-transactions |
node add-execute | consensus dev-node-add execute |
node update-prepare | consensus dev-node-update prepare |
node update-submit-transaction | consensus dev-node-update submit-transactions |
node update-execute | consensus dev-node-update execute |
node upgrade-prepare | consensus dev-node-upgrade prepare |
node upgrade-submit-transaction | consensus dev-node-upgrade submit-transactions |
node upgrade-execute | consensus dev-node-upgrade execute |
node delete-prepare | consensus dev-node-delete prepare |
node delete-submit-transaction | consensus dev-node-delete submit-transactions |
node delete-execute | consensus dev-node-delete execute |
node prepare-upgrade | consensus dev-freeze prepare-upgrade |
node freeze-upgrade | consensus dev-freeze freeze-upgrade |
node logs | deployment diagnostics logs |
node download-generated-files | No direct equivalent. Use deployment diagnostics all or deployment diagnostics debug based on intent. |
node states | consensus state download |
Notes
- Current command tree includes additional commands not present in legacy CLI (for example
ledger account predefined,rapid-fire load start, andconsensus node collect-jfr).
2.10 - Solo Image Cache
Overview
A Solo network runs roughly 29 container images (consensus node, mirror node,
JSON-RPC relay, Explorer, MinIO, and supporting services).
The image cache pre-pulls those images and stores them as local .tar
archives, so repeat deployments load them from disk instead of re-downloading
them from their registries.
Solo populates and uses the cache automatically in two places:
- At install time - Homebrew and npm installs pre-pull the default images.
- During
solo one-shotdeploys - Solo pulls and loads the cached images as pipeline phases before the network is deployed.
You can also manage the cache directly with the solo cache image commands.
Prerequisites
- Solo CLI v0.73.0 or later installed - the image cache was introduced in
Solo v0.73.0; earlier versions have no
solo cache imagecommand. See Quickstart.
Where the cache lives
Cached image archives are stored under your Solo home directory, in
~/.solo/cache/images/ (one archive per image).
Managing the cache
All commands live under solo cache image.
Pull images
Download the default (stable) images and write them to the cache. This is a
prerequisite for load.
solo cache image pull
Pass --edge to cache the edge (pre-release) component versions instead of the
stable defaults:
solo cache image pull --edge
You can also pin individual components with the per-component version flags
--mirror-node-version, --block-node-version, --relay-version, and
--explorer-version.
Load images into a cluster
Load the cached archives into a cluster. This step needs a prior pull and a
running cluster with a configured cluster reference (pull itself needs
neither a running cluster nor a Docker daemon).
solo cache image load --cluster-ref <cluster-ref>
<cluster-ref> is a Solo cluster reference: an alias Solo maps to a Kubernetes
context.
solo one-shotdeployments create one namedone-shot.- List the references you already have with
solo cluster-ref config list. - Create a new one with
solo cluster-ref config connect --cluster-ref <name> --context <kube-context>.
List cached archives
solo cache image list
Show cache status
Report which images are cached and which are missing. Pass --cluster-ref to
also compare against the images already loaded in a cluster.
solo cache image status --cluster-ref <cluster-ref>
Clear or prune the cache
Remove cached image archives with clear, or with prune (Solo v0.78.0 and
later):
solo cache image clear
solo cache image prune
Disabling the cache
The image cache is enabled by default. Each install/deploy path has its own opt-out:
| Context | Opt-out | Notes |
|---|---|---|
solo one-shot deploy | ENABLE_IMAGE_CACHE=false | Requires Solo v0.78.0 or later. |
| npm global install | SOLO_NO_CACHE=true | Skips the post-install image pull. |
| Homebrew install | HOMEBREW_NO_SOLO_CACHE | Set to any value (presence-based). Skips both the brew-level pull and the npm post-install pull. |
Caching a specific component version
Solo resolves the component versions it caches from environment variables,
not from CLI flags or solo.config.yaml. To cache a non-default version, set
the version environment variable on the deploy command:
MIRROR_NODE_VERSION=v0.150.0 solo one-shot single deploy
Note: Passing the version with the
--mirror-node-versionCLI flag (or insolo.config.yaml) changes the deployed component but not the cached images - the cache still uses the default versions, which can cause a cache miss on first deploy. Use the environment variable to keep the cache aligned with the deployed versions.
Troubleshooting
[SOLO-4049] Cache has not been materialized yet— theload,list,status,clear, andprunecommands require a populated cache. Runsolo cache image pullfirst, then retry the command.- The cache is empty after installing Solo. The install-time pull is
best-effort and can be skipped by a network hiccup. Populate it manually with
solo cache image pull. loadcannot find the target cluster. Confirm the cluster reference withsolo cluster-ref config list, then re-runloadwith the correct--cluster-ref.
2.11 - Solo Helm Chart Cache
Overview
A Solo network deployment installs a number of Helm charts (the Solo deployment charts, mirror node, JSON-RPC relay, Explorer, block node, MinIO, Prometheus, and the ingress controller). The chart cache pre-pulls those chart tarballs and stores them on disk, so deployments install them from the local cache instead of fetching them from their chart repositories or OCI registries.
The cache is used automatically: whenever Solo installs or upgrades a chart, it first checks the cache for a tarball matching the exact chart name and version being installed. On a match, the chart is installed from the local archive (no network fetch); otherwise Solo falls back to the normal network install.
You populate and manage the cache with the solo cache chart commands.
Prerequisites
- Solo CLI v0.82.0 or later installed - the chart cache was introduced in
Solo v0.82.0; earlier versions have no
solo cache chartcommand. See Quickstart.
Where the cache lives
Cached chart tarballs are stored under your Solo home directory, in
~/.solo/cache/charts/ - one archive per chart and version, named
<chart-name>__<version>.tar. This sits alongside the
image cache (~/.solo/cache/images/);
the two caches are managed independently.
What gets cached
solo cache chart pull caches the charts below. Each chart is pulled at the
version pinned in your Solo release, and each version can be overridden with an
environment variable (see
Using environment variables
for the current defaults):
| Chart | Version environment variable | Source |
|---|---|---|
solo-deployment | SOLO_CHART_VERSION | oci://ghcr.io/hashgraph/solo-charts |
solo-cert-manager | SOLO_CHART_VERSION | oci://ghcr.io/hashgraph/solo-charts |
solo-shared-resources | SOLO_CHART_VERSION | oci://ghcr.io/hashgraph/solo-charts |
hedera-mirror (mirror node) | MIRROR_NODE_VERSION | MIRROR_NODE_CHART_URL |
hedera-json-rpc (JSON-RPC relay) | RELAY_VERSION | JSON_RPC_RELAY_CHART_URL |
block-node-server (block node) | BLOCK_NODE_VERSION | BLOCK_NODE_CHART_URL |
hiero-explorer-chart (Explorer) | EXPLORER_VERSION | EXPLORER_CHART_URL |
kube-prometheus-stack | PROMETHEUS_STACK_VERSION | PROMETHEUS_STACK_CHART_URL |
prometheus-operator-crds | PROMETHEUS_OPERATOR_CRDS_VERSION | PROMETHEUS_OPERATOR_CRDS_CHART_URL |
operator (MinIO operator) | MINIO_OPERATOR_VERSION | MINIO_OPERATOR_CHART_URL |
haproxy-ingress (ingress controller) | INGRESS_CONTROLLER_VERSION | INGRESS_CONTROLLER_CHART_URL |
The Source column names the environment variable holding the chart repository
or OCI registry URL; those can be overridden too, for example to pull through an
internal mirror.
Not cached: the network load generator and metrics-server charts are intentionally excluded (metrics-server has no pinned version) and always install from the network.
Managing the cache
All commands live under solo cache chart. They accept the shared --quiet,
--cache-dir, and --dev-mode flags; no other flags are needed.
Pull charts
Download every chart in the table above and write it to the cache:
solo cache chart pull
The pull is incremental and safe to re-run: charts already in the cache are skipped. A chart that fails to download is reported and skipped, and the remaining charts still pull - re-run the command to retry the failed ones.
To cache a non-default version of a component, set its version environment variable on the pull:
MIRROR_NODE_VERSION=v0.150.0 solo cache chart pull
List cached charts
Show the cached charts (name and version):
solo cache chart list
Show cache status
Report how many charts are cached, their total size on disk, and which expected charts are missing:
solo cache chart status
Clear or prune the cache
Both remove the cached chart archives; neither touches the image cache. clear
deletes the archives Solo expects for the current versions, while prune
deletes the whole ~/.solo/cache/charts/ directory (including archives left
behind by other versions):
solo cache chart clear
solo cache chart prune
How deployments use the cache
When Solo installs or upgrades a chart (for example during
solo one-shot single deploy or solo cluster-ref config setup), it looks for
a cached tarball matching the exact chart name and version being installed:
- Cache hit - the chart installs from the local archive. No network fetch is
made, and Helm receives the local tarball path instead of the repository
reference. The debug log records the install with the message
from cached chart archive. - Cache miss - the chart installs from its repository or OCI registry over the network, exactly as it would without a cache. An empty or partial cache never breaks a deployment.
Because the lookup is an exact version match, keep the versions you pull and the
versions you deploy aligned. If you deploy a non-default component version (via
an environment variable or a CLI flag such as --mirror-node-version), pull the
cache with the matching environment variable first:
MIRROR_NODE_VERSION=v0.150.0 solo cache chart pull
MIRROR_NODE_VERSION=v0.150.0 solo one-shot single deploy
Otherwise the deployment simply misses the cache for that component and falls back to a network install.
Local chart directories win over the cache. If you point Solo at a local
chart directory (dev mode, e.g. --chart-dir), that directory is used and the
cache is bypassed for that chart.
Troubleshooting
- A chart failed to pull. Failures are per-chart: the failed chart is
reported and the rest of the pull continues. Re-run
solo cache chart pull- already-cached charts are skipped and only the missing ones are retried. - How do I confirm a deploy used the cache? Run
solo cache chart statusbefore deploying to confirm the charts are cached, and look forfrom cached chart archivein the debug log (~/.solo/logs/solo.log) after deploying. - A component still downloads its chart. Check that the cached version
matches the deployed version (
solo cache chart list); an exact-match lookup means any version drift falls back to the network. Also note the network load generator and metrics-server are never cached.
3 - Using Solo
Walk through submitting your first transaction to a local Solo network using the Hiero JavaScript, Java, or Go SDK.
Default service endpoints for a Solo one-shot deployment. Quick reference for the Hiero consensus gRPC address, Mirror Node REST URL, JSON-RPC Relay port, and Explorer URL — for both Solo 0.63+ and Solo 0.62 and earlier.
Learn how to locate and connect to ancillary services deployed alongside Solo networks, including Mirror Node Explorer, Block Nodes, and JSON-RPC Relay services.
Point your existing Ethereum tooling (Hardhat, ethers.js, Foundry, and MetaMask) at a local Hiero network via the Hiero JSON-RPC relay. This document covers enabling the relay, creating and configuring a Hardhat project, deploying a Solidity contract, using Foundry, and configuring wallets.
Learn how to run load tests against a Solo network using the Network Load Generator (NLG). Generate realistic transaction flows and stress-test your deployment to verify performance under load.
Test unreleased hiero-consensus-node changes end-to-end using Solo’s –local-build-path flag — no Docker image rebuild or registry push required.
3.1 - Accessing Solo Services
Add Mirror Node to a Solo network to stream and query transaction records, account history, and token data via the Hiero Mirror Node REST API.
3.1.1 - Using Solo with Mirror Node
Overview
The Hiero Mirror Node stores the full transaction history of your local Solo network and exposes it through several interfaces:
- A web-based block explorer (Hiero Mirror Node Explorer) at
http://localhost:38080/localnet/dashboard(Solo 0.63+) orhttp://localhost:8080/localnet/dashboard(Solo 0.62 and earlier). - A REST API via the mirror-ingress service at
http://localhost:38081(Solo 0.63+) orhttp://localhost:8081(Solo 0.62 and earlier) (recommended entry point — routes to the correct REST implementation). - A gRPC endpoint for mirror node subscriptions.
Important: The port numbers in this document are Solo’s default targets. If any port is already in use on your machine when Solo starts, Solo automatically selects the next available port. If an endpoint does not work, check the actual ports assigned to your deployment — see Port Reference below.
This guide walks you through adding Mirror Node and the Hiero Explorer to a Solo network, and shows you how to query transaction data and create accounts.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness - your local environment meets all hardware and software requirements, including Docker and Solo.
- Quickstart - you have a running Solo
network deployed using
solo one-shot single deploy. - To find your deployment name at any time, run
solo one-shot show deployment(see Capture your deployment name).
Step 1: Deploy Solo with Mirror Node
Note: If you deployed your network using one-shot, Falcon, or the Task Tool, Mirror Node is already running - skip to Step 2: Access the Mirror Node Explorer.
Fresh manual Deployment
If you are building a custom network or adding the mirror node to an existing deployment, run the following commands in sequence.
On native Windows (PowerShell), set the environment variables with $env: instead of export (and reference them as $env:SOLO_CLUSTER_NAME, etc., in the commands that follow):
$env:SOLO_CLUSTER_NAME = 'solo-cluster'
$env:SOLO_NAMESPACE = 'solo-deployment'
$env:SOLO_CLUSTER_SETUP_NAMESPACE = 'solo-cluster-setup'
$env:SOLO_DEPLOYMENT = 'solo-deployment'
# Set environment variables
export SOLO_CLUSTER_NAME=solo-cluster
export SOLO_NAMESPACE=solo-deployment
export SOLO_CLUSTER_SETUP_NAMESPACE=solo-cluster-setup
export SOLO_DEPLOYMENT=solo-deployment
# Reset environment
rm -Rf ~/.solo
kind delete cluster -n "${SOLO_CLUSTER_NAME}"
kind create cluster -n "${SOLO_CLUSTER_NAME}"
# Configure cluster
solo cluster-ref config setup \
--cluster-setup-namespace "${SOLO_CLUSTER_SETUP_NAMESPACE}"
solo cluster-ref config connect \
--cluster-ref ${SOLO_CLUSTER_NAME} \
--context kind-${SOLO_CLUSTER_NAME}
# Create deployment
solo deployment config create \
--namespace "${SOLO_NAMESPACE}" \
--deployment "${SOLO_DEPLOYMENT}"
solo deployment cluster attach \
--deployment "${SOLO_DEPLOYMENT}" \
--cluster-ref ${SOLO_CLUSTER_NAME} \
--num-consensus-nodes 2
# Generate keys and deploy consensus nodes
solo keys consensus generate \
--deployment "${SOLO_DEPLOYMENT}" \
--gossip-keys --tls-keys \
-i node1,node2
solo consensus network deploy --deployment "${SOLO_DEPLOYMENT}" -i node1,node2
solo consensus node setup --deployment "${SOLO_DEPLOYMENT}" -i node1,node2
solo consensus node start --deployment "${SOLO_DEPLOYMENT}" -i node1,node2
# Add mirror node and explorer
solo mirror node add \
--deployment "${SOLO_DEPLOYMENT}" \
--cluster-ref ${SOLO_CLUSTER_NAME} \
--enable-ingress \
--pinger
solo explorer node add \
--deployment "${SOLO_DEPLOYMENT}" \
--cluster-ref ${SOLO_CLUSTER_NAME}
Note: The
--pingerflag insolo mirror node addstarts a background service that sends transactions to the network at regular intervals. This is required because mirror node record files are only imported when a new record file is created - without it, the mirror node will appear empty until the next transaction occurs naturally.
Step 2: Access the Mirror Node Explorer
Once Mirror Node is running, open the Hiero Explorer in your browser at:
http://localhost:38080/localnet/dashboard
Note: If you are using Solo 0.62 or earlier, the Explorer is at
http://localhost:8080/localnet/dashboard. If that port does not work, check the actual port assigned to your deployment — see Port Reference.
The Explorer lets you browse accounts, transactions, tokens, and contracts on your Solo network in real time.
Step 3: Create Accounts and View Transactions
Create test accounts and observe them appearing in the Explorer:
solo ledger account create --deployment solo-deployment --hbar-amount 100
solo ledger account create --deployment solo-deployment --hbar-amount 100
Open the Explorer at http://localhost:38080/localnet/dashboard (Solo 0.63+) or http://localhost:8080/localnet/dashboard (Solo 0.62 and earlier) to see the new accounts and their transactions recorded by the Mirror Node. If the port does not work, check your actual port assignments — see Port Reference.
You can also use the Hiero JavaScript SDK to create a topic, submit a message, and subscribe to it.
Step 4: Access Mirror Node APIs
Option A: Mirror-Ingress (localhost:38081)
Use localhost:38081 (Solo 0.63+) for all Mirror Node REST API access. The mirror-ingress
service routes requests to the correct REST implementation automatically. This
is important because certain endpoints are only supported in the newer
rest-java version.
# List recent transactions
curl -s "http://localhost:38081/api/v1/transactions?limit=5"
# Get account details
curl -s "http://localhost:38081/api/v1/accounts/0.0.2"
Note: If you are using Solo 0.62 or earlier, use
localhost:8081instead oflocalhost:38081.localhost:5551(the legacy Mirror Node REST API direct endpoint) is being phased out. Always use the mirror-ingress port to ensure compatibility with all endpoints.
If you need to access it directly:
kubectl port-forward svc/mirror-1-rest -n "${SOLO_NAMESPACE}" 5551:80 &
curl -s "http://${REST_IP:-127.0.0.1}:5551/api/v1/transactions?limit=1"
Option B: Mirror Node gRPC
For mirror node gRPC subscriptions (e.g. topic messages, account balance updates), enable port-forwarding manually if not already active:
kubectl port-forward svc/mirror-1-grpc -n "${SOLO_NAMESPACE}" 5600:5600 &
Then verify available services:
grpcurl -plaintext "${GRPC_IP:-127.0.0.1}:5600" list
Option C: Mirror Node REST-Java (Direct Access)
For direct access to the rest-java service (bypassing the ingress):
kubectl port-forward service/mirror-1-restjava -n "${SOLO_NAMESPACE}" 8084:80 &
# Example: NFT allowances
curl -s "http://${REST_IP:-127.0.0.1}:8084/api/v1/accounts/0.0.2/allowances/nfts"
In most cases you should use localhost:38081 (Solo 0.63+) or localhost:8081 (Solo 0.62 and earlier) instead.
Port Reference
For the full network endpoint reference (consensus gRPC, Mirror Node REST, JSON-RPC Relay, and Explorer), see Service Endpoints. The table below covers mirror-node-specific ports, including those accessible only via manual
kubectl port-forward.
The ports listed below are Solo’s default targets. Solo checks each port before opening a tunnel - if the port is already in use, Solo picks the next available one and logs Using available port <port>. If an endpoint is not reachable, check the actual ports your deployment is using with solo deployment config ports --deployment <deployment-name> - see Port availability for the full set of commands.
The default local ports depend on your Solo version:
Solo 0.63 and later (current defaults):
| Service | Local Port | Access Method |
|---|---|---|
| Hiero Explorer | 38080 | Browser (--enable-ingress) |
| Mirror Node (all-in-one) | 38081 | HTTP (--enable-ingress) |
| Mirror Node REST API | 5551 | kubectl port-forward (manual) |
| Mirror Node gRPC | 5600 | kubectl port-forward |
| Mirror Node REST Java | 8084 | kubectl port-forward |
Solo 0.62 and earlier:
| Service | Local Port | Access Method |
|---|---|---|
| Hiero Explorer | 8080 | Browser (--enable-ingress) |
| Mirror Node (all-in-one) | 8081 | HTTP (--enable-ingress) |
| Mirror Node REST API | 5551 | kubectl port-forward |
| Mirror Node gRPC | 5600 | kubectl port-forward |
| Mirror Node REST Java | 8084 | kubectl port-forward |
Restoring Port-Forwards
If port-forwards are interrupted — for example after a system restart — restore them by re-running the relevant component add commands. These commands are idempotent and will reattach port-forwards without redeploying:
solo mirror node add --deployment "${SOLO_DEPLOYMENT}"
solo explorer node add --deployment "${SOLO_DEPLOYMENT}"
Tearing Down
To remove the Mirror Node from a running deployment:
solo mirror node destroy --deployment "${SOLO_DEPLOYMENT}" --force
To remove the Hiero Mirror Node Explorer:
solo explorer node destroy --deployment "${SOLO_DEPLOYMENT}" --force
For full network teardown, see Step-by-Step Manual Deployment-Cleanup.
3.2 - Service Endpoints
Overview
After a successful solo one-shot single deploy, Solo sets up port-forwards to
the following local services. Use these endpoints to connect your application,
SDK, or tooling to the running network.
Note: The ports below are Solo’s default targets. If a port is already in use on your machine, Solo automatically selects the next available port and logs
Using available port <port>. See Port availability for how to look up the ports your deployment is actually using.
Solo 0.63 and later (current defaults)
| Service | Endpoint | Description |
|---|---|---|
| Explorer UI | http://localhost:38080 | Web UI for inspecting accounts and transactions. |
| Consensus node (gRPC) | localhost:35211 | gRPC endpoint for submitting transactions. |
| Mirror node REST API | http://localhost:38081 | REST API for querying historical data. |
| JSON-RPC relay | http://localhost:37546 | Ethereum-compatible JSON-RPC endpoint. |
Verify the endpoints
# Consensus node (gRPC)
nc -zv localhost 35211
# Mirror node REST API
curl http://localhost:38081/api/v1/transactions
# JSON-RPC relay
curl -X POST http://localhost:37546 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# Consensus node (gRPC)
Test-NetConnection localhost -Port 35211
# Mirror node REST API
Invoke-RestMethod http://localhost:38081/api/v1/transactions
# JSON-RPC relay
Invoke-RestMethod -Method Post -Uri 'http://localhost:37546' `
-ContentType 'application/json' `
-Body '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
macOS note: Running
nc -zv localhost 35211may print two lines:nc: connectx to localhost port 35211 (tcp) failed: Connection refused Connection to localhost port 35211 [tcp/*] succeeded!The first line is a failed IPv6 attempt — this is expected on macOS. The second line confirms the IPv4 connection succeeded. The port is reachable.
Note: In PowerShell,
curlis an alias forInvoke-WebRequest, so bashcurlflags will not work. Usecurl.exeexplicitly if you prefer the bash-style syntax.
Solo 0.62 and earlier
If you are using Solo 0.62 or earlier, the default port-forward targets differ:
| Service | Endpoint | Description |
|---|---|---|
| Explorer UI | http://localhost:8080 | Web UI for inspecting accounts and transactions. |
| Consensus node (gRPC) | localhost:50211 | gRPC endpoint for submitting transactions. |
| Mirror node REST API | http://localhost:8081 | REST API for querying historical data (via mirror-ingress). |
| JSON-RPC relay | http://localhost:7546 | Ethereum-compatible JSON-RPC endpoint. |
Note:
localhost:5551is the direct Mirror Node REST service, accessible only via manualkubectl port-forward, and is being phased out. Always use the ingress-based port (8081for Solo 0.62 and earlier,38081for Solo 0.63+).
Connecting your application
Quick reference for SDK and tooling configuration (Solo 0.63 and later):
- Hiero SDK (gRPC):
localhost:35211, node account ID0.0.3 - EVM tools (JSON-RPC):
http://localhost:37546 - Mirror Node REST:
http://localhost:38081/api/v1/
For SDK-specific connection examples, see:
Port availability
Solo uses kubectl port-forward to tunnel traffic from your machine to services
running inside Kubernetes. Before opening each tunnel, Solo tries the configured
port:
- If the port is free, Solo logs:
Using requested port <port>. - If the port is already occupied (by another process, or by a previous Solo
session that did not clean up its port-forwards), Solo finds the next
available port and logs:
Using available port <port>.
The actual ports used are printed at the end of solo one-shot single deploy.
You can also look them up at any time with the Solo CLI, using your deployment
name (see Capture your deployment name).
To view the active port assignments:
solo deployment config ports --deployment <deployment-name>
The output directory is one-shot-<deployment-name>, and the default deployment
name is one-shot. So the default output directory is ~/.solo/one-shot-one-shot/.
cat ~/.solo/one-shot-one-shot/forwards
Get-Content "$env:USERPROFILE\.solo\one-shot-one-shot\forwards"
*** Consensus node gRPC ***
-------------------------------------------------------------------------------
- component 1: localhost:35211 -> pod:50211
solo deployment config info --deployment one-shot
To restore port-forwards after a system restart without redeploying:
solo deployment port-forwards refresh --deployment one-shot
Note:
solo deployment refresh port-forwardsstill works but is deprecated in favor ofsolo deployment port-forwards refreshand will be removed in a future release.
To stop all port-forwards for a deployment (for example, before shutting down your machine):
solo deployment port-forwards stop --deployment one-shot
This closes the underlying kubectl port-forward processes and removes them
from the deployment’s remote config, so they are not restored automatically.
Run solo deployment port-forwards refresh --deployment one-shot afterward to
re-establish them.
3.3 - Using Solo with Hiero SDKs
Overview
The Hiero SDKs let you build and test applications on the Hiero network using JavaScript / TypeScript, Java, or Go. This guide walks you through launching a local Solo network, locating its bootstrap operator account, setting up a project for your chosen SDK, and running example transactions. The Solo-side steps are identical across all three SDKs; the language-specific steps appear in tabs you can switch between.
Prerequisites
Before proceeding, ensure you have completed the following:
Your local environment meets all hardware and software requirements, including Docker, kubectl, and Solo.
The shared baseline tools:
Requirement Version Purpose Docker Desktop Latest Runs the Solo cluster containers Solo Latest stable Deploys and manages the local network
Plus the SDK-specific toolchain for the language you’ll use:
Note: Solo uses Docker Desktop to spin up local Hiero consensus and mirror nodes. Ensure Docker Desktop is running before deploying the local network.
Step 1: Launch a Local Solo Network
Deploy a local Solo network by following the Solo Quickstart. Once it’s running, retrieve your deployment name with solo one-shot show deployment - the rest of this guide refers to it as <your-deployment-name>.
Step 2: Install the SDK
Install the Hiero SDK for your language.
Initialize a Node.js project and install the SDK from npm:
mkdir solo-js-demo && cd solo-js-demo
npm init -y
npm install @hiero-ledger/sdk
For the full SDK source tree (with the bundled examples/ directory), follow the Hiero JavaScript SDK README. The repository uses pnpm workspaces + go-task to build.
Follow the Hiero Java SDK quickstart to set up a Gradle (or Maven) project. The minimum dependency set:
implementation("com.hedera.hashgraph:sdk:2.72.0")
implementation("io.grpc:grpc-netty-shaded:1.64.0")
implementation("org.slf4j:slf4j-nop:2.0.9")
Initialize a Go module and add the Hiero Go SDK:
mkdir solo-go-demo && cd solo-go-demo
go mod init solo-go-demo
go get github.com/hiero-ledger/hiero-sdk-go/v2@v2.80.0
Go 1.25 or higher is required (per go.mod in the SDK). See the Hiero Go SDK README for the full setup walkthrough.
Step 3: Locate Your Operator Credentials
solo one-shot single deploy provisions pre-funded accounts and writes their
credentials to accounts.json. Any account from this file can
serve as your SDK operator — 0.0.2 is used as the example throughout this
guide, but it is not required. You do not need to call
solo ledger account create for the examples in this guide.
Tip: Account credentials are also printed to the terminal at the end of
solo one-shot single deploy. If you missed the output, use the steps below to retrieve them from disk.
Print the operator credentials:
cat ~/.solo/one-shot-<your-deployment-name>/accounts.jsonTip: If you are unsure of your deployment name, run
solo one-shot show deployment— it prints the deployment name and the full path toaccounts.json.Expected output:
{ "systemAccounts": [ { "name": "Operator", "accountId": "0.0.2", "publicKey": "302a300506032b65700321000aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92", "privateKey": "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137" } ], "createdAccounts": [ { "accountId": "0.0.1002", "privateKey": "0x105d050185...", "balance": "1000000 ℏ", "group": "ecdsa-alias" }, ... ] }The
systemAccounts[0]entry (0.0.2) holds an Ed25519 key in DER format and is used as the operator example in this guide. ThecreatedAccountsarray contains additional pre-funded ECDSA accounts (0.0.1002–0.0.1011) useful for EVM workflows — any of these can also be used as an operator.Save the
accountIdandprivateKeyvalues fromsystemAccounts[0]— you will configure the SDK with them in the next step.
EVM tooling note: For ethers.js, Hardhat, or Foundry, use one of the
createdAccountsentries; theirprivateKeyvalues are already in 0x-prefixed hex form. See Using Solo with EVM Tools for the full EVM-side workflow.
Step 4: Configure the SDK to Connect to Solo
Each SDK reads operator credentials and the network endpoint differently. Pick your language tab below.
The Hiero JavaScript SDK uses environment variables to authenticate the operator account. Create a .env file at the root of the hiero-sdk-js directory:
cd hiero-sdk-js
cat > .env <<EOF
# Operator account ID (systemAccounts[0].accountId from Step 3)
OPERATOR_ID="0.0.2"
# Operator private key (systemAccounts[0].privateKey from Step 3)
OPERATOR_KEY="302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"
# Required by LocalProvider in the SDK example scripts (Step 5).
# Not used by the Client.fromConfig() snippet below, but harmless to include.
HEDERA_NETWORK="local-node"
EOF
source .env
Important:
OPERATOR_KEYmust be set to theprivateKeyvalue, not thepublicKey. The private key is the longer DER-encoded string beginning with302e.... The example scripts also requireHEDERA_NETWORK- they throw “LocalProvider requires theHEDERA_NETWORKenvironment variable to be set” if it is missing.
Security: Never commit
.envto source control - the file holds the operator’s private key. Add.envto your repository’s.gitignore.
Configure the client with the Solo 0.63+ port-forwards using Client.fromConfig(). The SDK’s built-in Client.forLocalNode() preset is hardcoded to localhost:50211, which does not match Solo 0.63+ defaults (localhost:35211 for consensus gRPC, localhost:38081 for the mirror node ingress). Use the explicit network map shown below instead:
import { Client, AccountId } from "@hiero-ledger/sdk";
const network = { "127.0.0.1:35211": AccountId.fromString("0.0.3") };
const mirrorNetwork = "127.0.0.1:38081";
const client = Client.fromConfig({
network,
mirrorNetwork,
// Required: the SDK's address-book refresh otherwise pulls in the
// hardcoded 50211/50212 ports, which Solo 0.63+ does not expose.
scheduleNetworkUpdate: false,
});
client.setOperator(process.env.OPERATOR_ID!, process.env.OPERATOR_KEY!);
Create a .env file at the project root to hold your operator credentials:
cat > .env <<EOF
# Operator account ID (systemAccounts[0].accountId from Step 3)
OPERATOR_ID=0.0.2
# Operator private key (systemAccounts[0].privateKey from Step 3)
OPERATOR_KEY=302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137
EOF
Important:
OPERATOR_KEYmust be theprivateKeyvalue, not thepublicKey. The private key is the longer DER-encoded string beginning with302e....
Security: Never commit
.envto source control - the file holds the operator’s private key. Add.envto your repository’s.gitignore.
Load the env variables:
set -a; source .env; set +a
Configure the client in src/main/java/Main.java. Unlike the JavaScript SDK (which ships a LocalProvider / Client.forName("local-node") preset), the Hiero Java SDK has no local-node preset - Client.forName(...) only accepts "mainnet", "testnet", or "previewnet" and throws IllegalArgumentException otherwise. Build the network map explicitly using Client.forNetwork(Map) against Solo’s auto-forwarded ports:
import com.hedera.hashgraph.sdk.AccountId;
import com.hedera.hashgraph.sdk.AccountInfoQuery;
import com.hedera.hashgraph.sdk.Client;
import com.hedera.hashgraph.sdk.PrivateKey;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class Main {
public static void main(String[] args) throws Exception {
String operatorId = System.getenv("OPERATOR_ID");
String operatorKey = System.getenv("OPERATOR_KEY");
if (operatorId == null || operatorKey == null) {
throw new IllegalStateException(
"Set OPERATOR_ID and OPERATOR_KEY env vars before running.");
}
Map<String, AccountId> network = new HashMap<>();
network.put("127.0.0.1:35211", AccountId.fromString("0.0.3"));
Client client = Client.forNetwork(network);
client.setMirrorNetwork(List.of("127.0.0.1:38081"));
client.setOperator(
AccountId.fromString(operatorId),
PrivateKey.fromString(operatorKey));
// ... transactions and queries go here ...
client.close();
}
}
Client.setMirrorNetwork(List<String>)declaresthrows InterruptedException, and queries/transactions throwTimeoutException/PrecheckStatusException. Declaringthrows Exceptiononmainkeeps the example readable; wrap with explicit try/catch in production code.
The Hiero Go SDK reads operator credentials and the target network from environment variables.
Create a .env file at the project root:
cat > .env <<'EOF'
# Operator account ID (systemAccounts[0].accountId from Step 3)
export OPERATOR_ID="0.0.2"
# Operator private key (systemAccounts[0].privateKey from Step 3)
export OPERATOR_KEY="302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"
# Network name. "localhost" is the SDK's local-node preset; only used by
# ClientForName(...) - the explicit ClientForNetworkV2 path below ignores it.
export HEDERA_NETWORK="localhost"
EOF
source .env
Important:
OPERATOR_KEYmust be theprivateKeyvalue, not thepublicKey. The private key is the longer DER-encoded string beginning with302e....
Security: Never commit
.envto source control. Add it to.gitignore.
Configure the client in main.go. The Hiero Go SDK ships a ClientForName preset that recognizes "local" and "localhost", but the preset is hardcoded to 127.0.0.1:50211 (consensus gRPC) and 127.0.0.1:5600 (mirror gRPC) - ports Solo does not expose by default (Solo’s auto-port-forwards use 35211 and 38081). The simplest path that works out of the box is to build the network map explicitly with ClientForNetworkV2:
package main
import (
"fmt"
"os"
hiero "github.com/hiero-ledger/hiero-sdk-go/v2/sdk"
)
func main() {
operatorID := os.Getenv("OPERATOR_ID")
operatorKey := os.Getenv("OPERATOR_KEY")
if operatorID == "" || operatorKey == "" {
fmt.Fprintln(os.Stderr, "Set OPERATOR_ID and OPERATOR_KEY env vars before running.")
os.Exit(1)
}
network := map[string]hiero.AccountID{
"127.0.0.1:35211": {Account: 3},
}
client, err := hiero.ClientForNetworkV2(network)
if err != nil {
panic(err)
}
defer client.Close()
client.SetMirrorNetwork([]string{"127.0.0.1:38081"})
opAccID, err := hiero.AccountIDFromString(operatorID)
if err != nil {
panic(err)
}
opKey, err := hiero.PrivateKeyFromString(operatorKey)
if err != nil {
panic(err)
}
client.SetOperator(opAccID, opKey)
// ... transactions and queries go here ...
}
The network map’s value uses the struct literal
hiero.AccountID{Account: 3}(matchesnetwork-node1’s0.0.3). This is shorter thanhiero.AccountIDFromString("0.0.3")and matches the form upstream examples use.
Verify your configuration
Add an AccountInfoQuery for the operator and run it to confirm the client reaches Solo.
In your TypeScript/JavaScript code, after building client:
const info = await new AccountInfoQuery()
.setAccountId(AccountId.fromString(process.env.OPERATOR_ID!))
.execute(client);
console.log("Account ID :", info.accountId.toString());
console.log("Balance :", info.balance.toString());
In Main.java, after setOperator(...):
var info = new AccountInfoQuery()
.setAccountId(AccountId.fromString(operatorId))
.execute(client);
System.out.println("Account ID : " + info.accountId);
System.out.println("Balance : " + info.balance);
Then run gradle run.
Expected output:
Account ID : 0.0.2
Balance : 49989999499.9946 ℏ
In main.go, after SetOperator(...):
info, err := hiero.NewAccountInfoQuery().
SetAccountID(opAccID).
Execute(client)
if err != nil {
panic(err)
}
fmt.Printf("Account ID : %s\n", info.AccountID)
fmt.Printf("Balance : %s\n", info.Balance)
Then run go run ..
Expected output:
Account ID : 0.0.2
Balance : 4.99899994792001e+10 ℏ
The Hbar value is printed in scientific notation by default; format it with info.Balance.As(hiero.HbarUnits.Hbar) or info.Balance.AsTinybar() for decimal HBAR or tinybars.
The exact balance differs slightly between deployments; what matters is that an AccountInfo returns at all - that proves the gRPC pipe to the consensus node is alive and the operator credentials are valid.
Step 5: Run Transactions Against Solo
Heads up (JavaScript and Go only): The SDK example programs use the SDK’s local-node preset (
LocalProviderin JS,ClientForName("localhost")in Go), which is hardcoded to127.0.0.1:50211(consensus gRPC) and127.0.0.1:5600(mirror gRPC). Solo doesn’t expose those ports by default, so the upstream example programs cannot reach the network out of the box. Either follow Make the examples reachable below, or rewrite the example to use theClient.fromConfig(JS) /ClientForNetworkV2(Go) pattern from Step 4. The Java SDK has no local-node preset, so this caveat does not apply there.
Make the examples reachable
Pick one:
Option A - forward Solo’s services to the SDK’s legacy ports (run examples unchanged):
kubectl port-forward svc/haproxy-node1-svc -n <your-deployment-name> 50211:50211 &
kubectl port-forward svc/mirror-1-grpc -n <your-deployment-name> 5600:5600 &
The kubectl namespace matches <your-deployment-name> for default one-shot deploys.
Option B - edit the example to use the Client.fromConfig({ ..., scheduleNetworkUpdate: false }) pattern from Step 4. No port-forwarding needed.
No additional setup required. The Client.forNetwork(Map) pattern from
Step 4 hits Solo’s auto-forwarded
ports (35211 consensus, 38081 mirror) directly.
Pick one:
Option A - forward Solo’s services to the SDK’s legacy ports (run upstream examples with HEDERA_NETWORK="localhost" unchanged):
kubectl port-forward svc/haproxy-node1-svc -n <your-deployment-name> 50211:50211 &
kubectl port-forward svc/mirror-1-grpc -n <your-deployment-name> 5600:5600 &
Option B - use ClientForNetworkV2 directly (the pattern shown in Step 4). No port-forwarding needed.
Try a tutorial against your Solo network
Once your client is configured (Step 4), the canonical Hiero / Hedera SDK tutorials run against Solo the same way they run against testnet or mainnet - only the network endpoint changes. Pick a tutorial and follow it as written:
- Create an account
- Create a topic
- Transfer cryptocurrency
- Full tutorial index: Hiero / Hedera SDK guides
Each SDK also ships a runnable examples/ directory with
dozens of additional patterns - token creation, smart contract deployment,
HCS pub/sub, scheduled transactions, and more.
Verify transactions you submit in the Hiero Explorer: http://localhost:38080/localnet/dashboard.
Step 6: Tear Down the Network
When you are finished, remove the local consensus node, mirror node, block node, relay, explorer, and all data volumes:
solo one-shot single destroy \
--deployment <your-deployment-name>
Optional: Manage Files on the Network
Solo provides CLI commands to create and update files stored on the Hiero File Service.
Create a New File
solo ledger file create \
--deployment <your-deployment-name> \
--file-path ./config.json
This command:
- Creates a new file on the network and returns a system-assigned file ID.
- Automatically splits files larger than 4 KB into chunks using
FileAppendTransaction. - Verifies that the uploaded content matches the local file.
Update an Existing File
solo ledger file update \
--deployment <your-deployment-name> \
--file-id 0.0.1234 \
--file-path ./updated-config.json
This command:
- Verifies the file exists on the network (errors if not found).
- Replaces the file content and re-verifies the upload.
- Automatically handles chunking for large files (>4 KB).
Note: For files larger than 4 KB, both commands split content into 4 KB chunks and display per-chunk progress during the append phase.
Inspect Transactions in Hiero Explorer
Open the Hiero Explorer to visually inspect submitted transactions, accounts, topics, and files. The Solo Quickstart’s Access your local network section lists the Explorer URL and port-availability behavior. Once it’s open, search by account ID, transaction ID, or topic ID to confirm that your transactions reached consensus.
Retrieving Logs
Solo writes logs to ~/.solo/logs/:
| Log File | Contents |
|---|---|
solo.log | Human-readable Solo CLI output and lifecycle events |
solo.ndjson | Newline-delimited JSON of the same events (authoritative, machine-readable) |
The Solo log is useful for debugging connectivity issues between the SDK and your local Solo network.
SDK logging
For SDK-side logs (which logger each SDK uses and how to configure it), see the upstream docs:
- JavaScript: Hiero JS SDK README
- Java: Hiero Java SDK logging guide
- Go: Hiero Go SDK README
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
LocalProvider requires the HEDERA_NETWORK environment variable to be set (JS) | HEDERA_NETWORK missing from .env, or .env not sourced in this shell | Add HEDERA_NETWORK="local-node" to .env; then source .env |
Dependency resolution is looking for a library compatible with JVM runtime version 17, but 'com.hedera.hashgraph:sdk:2.72.0' is only compatible with JVM runtime version 21 or newer (Java) | JDK 17 target in build.gradle.kts | Set sourceCompatibility = JavaVersion.VERSION_21 and ensure the JDK on PATH is v21+ |
IllegalArgumentException: Name must be one-of 'mainnet', 'testnet', or 'previewnet' (Java) | Called Client.forName("local-node") | Use Client.forNetwork(Map) + setMirrorNetwork(List); Java SDK has no local-node preset |
go: module ... requires go >= 1.25 (Go) | Local Go is older than the SDK’s go.mod floor | Upgrade Go to v1.25+; on macOS, brew install go |
TimeoutException from query or transaction (all SDKs) | Consensus node not actually serving (deploy reported a NodesStarted timeout even though the pod is Running) | Run solo one-shot single destroy --deployment <name> then solo one-shot single deploy; the second attempt usually succeeds |
SDK calls fail; 127.0.0.1:35211 shows as not listening (all SDKs) | Solo’s auto-port-forward for consensus gRPC died after deploy | Restore manually: kubectl port-forward svc/haproxy-node1-svc -n <your-deployment-name> 35211:50211 & |
| Upstream SDK example hangs against Solo (JS, Go) | Example uses the SDK’s local-node preset, hardcoded to ports Solo doesn’t expose | Follow Option A or B in Make the examples reachable |
INVALID_SIGNATURE receipt error | OPERATOR_KEY set to public key instead of private key | Re-check your .env - use the privateKey field value |
INSUFFICIENT_TX_FEE | Operator account has no HBAR | Use a pre-funded createdAccounts entry or top up the operator |
Resources
- Solo operational workflows - Solo examples directory (node management, state backup/restore, multi-cluster setups, version upgrades, etc.).
- SDK examples and API references:
- JavaScript - hiero-sdk-js examples · JSDoc
- Java - hiero-sdk-java examples · Javadoc
- Go - hiero-sdk-go examples · godoc
- EVM workflows - Using Solo with EVM Tools.
- Solo cluster internals - Accessing Solo Services.
3.4 - Using Solo with EVM Tools
Overview
Hiero is EVM-compatible. The Hiero JSON-RPC relay exposes a standard Ethereum JSON-RPC interface on your local Solo network, letting you use familiar EVM tools without modification.
This guide walks you through:
- Launching a Solo network with the JSON-RPC relay enabled.
- Retrieving ECDSA accounts for EVM tooling.
- Creating and configuring a Hardhat project against the relay.
- Deploying and interacting with a Solidity contract.
- Deploying, calling and testing the same contract with Foundry (
forgeandcast). - Verifying transactions via the Explorer and Mirror Node.
- Configuring ethers.js and MetaMask.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness - your local environment meets all hardware and software requirements, including Docker and Solo.
- Quickstart - you are comfortable running Solo deployments.
You will also need:
- Git - to clone the optional pre-built example.
- Taskfile - only required if using the automated example.
Step 1: Launch a Solo Network with the JSON-RPC Relay
The easiest way to start a Solo network with the relay pre-configured is via
one-shot single deploy, which provisions the consensus node, mirror node,
Hiero Mirror Node Explorer, and the Hiero JSON-RPC relay in a single step:
npx @hiero-ledger/solo one-shot single deploy
This command:
- Creates a local Kind Kubernetes cluster.
- Deploys a Hiero consensus node, mirror node, and Hiero Mirror Node Explorer.
- Deploys the Hiero JSON-RPC relay and exposes it at
http://localhost:37546(Solo 0.63+). - Generates three groups of pre-funded accounts, including ECDSA (EVM-compatible) accounts.
Relay endpoint summary (Solo 0.63 and later):
Property Value RPC URL http://localhost:37546Chain ID 298Currency symbol HBARIf you are using Solo 0.62 or earlier, the relay is at
http://localhost:7546.
Adding the Relay to an Existing Deployment
If you already have a running Solo network without the relay, see Step 10: Deploy JSON-RPC Relay in the Step-by-Step Manual Deployment guide for full instructions, then return here once your relay is running on http://localhost:37546 (Solo 0.63+) or http://localhost:7546 (Solo 0.62 and earlier).
To remove the relay when you no longer need it, see Cleanup Step 1: Destroy JSON-RPC Relay in the same guide.
Step 2: Retrieve Your ECDSA Account and Private Key
one-shot single deploy creates ECDSA alias accounts, which are required for EVM tooling such as Hardhat, ethers.js, Foundry, and MetaMask.
These accounts and their private keys are saved to a cache directory on completion.
Note: ED25519 accounts are not compatible with Hardhat, ethers.js, Foundry, or MetaMask when used via the JSON-RPC interface. Always use the ECDSA keys from accounts.json for EVM tooling.
To find your deployment name, run
solo one-shot show deployment(see Capture your deployment name).Then open the accounts file at:
~/.solo/one-shot-<deployment-name>/accounts.jsonOpen that file to retrieve your ECDSA keys and EVM address. Each account entry contains:
- An ECDSA private key - 64 hex characters with a
0xprefix (e.g.0x105d0050...). - An ECDSA public key - the corresponding public key.
- An EVM address - derived from the public key (e.g.
0x70d379d473e2005bb054f50a1d9322f45acb215a). In Hiero terminology, this means the account has an EVM address aliased from its ECDSA public key.
0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524 0x2e1d968b041d84dd120a5860cee60cd83f9374ef527ca86996317ada3d0d03e7 ...- An ECDSA private key - 64 hex characters with a
Export the private key for one account as an environment variable - never hardcode private keys in source files:
export SOLO_EVM_PRIVATE_KEY="0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524"
$env:SOLO_EVM_PRIVATE_KEY = '0x105d0050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524'
Step 3: Create and Configure a Hardhat Project
Option A: Use the Pre-Built Solo Example (Recommended for First Time)
A ready-to-run Hardhat project is provided in the Solo repository. Skip to Step 4 after cloning:
git clone https://github.com/hiero-ledger/solo.git
cd solo/examples/hardhat-with-solo/hardhat-example
npm install
Option B: Create a New Hardhat Project from Scratch
If you want to integrate Solo into your own project:
mkdir solo-hardhat && cd solo-hardhat
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npx hardhat init
When prompted, choose TypeScript project or JavaScript project based on your preference.
Install dependencies:
npm install
Configure Hardhat to Connect to the Solo Relay
Create or update hardhat.config.ts to point at the Solo JSON-RPC relay.
The chainId of 298 is required - Hardhat will reject transactions if it
does not match the network:
import { defineConfig } from "hardhat/config";
import hardhatToolboxMochaEthers from "@nomicfoundation/hardhat-toolbox-mocha-ethers";
const config = defineConfig({
plugins: [hardhatToolboxMochaEthers],
solidity: "0.8.28",
networks: {
my_solo_deployment: {
type: "http",
url: "http://127.0.0.1:37546",
chainId: 298,
// Load from environment - never commit private keys to source control
accounts: process.env.SOLO_EVM_PRIVATE_KEY
? [process.env.SOLO_EVM_PRIVATE_KEY]
: [],
},
},
});
export default config;
Important: This is the Hardhat v3 config format used by the bundled example (Hardhat 3.x). Each network needs an explicit
type: "http", andchainId: 298must be set - withouttype/chainId, Hardhat v3 fails withHHE40000: No network with chain id "298" foundwhen connecting to the relay. The network key (my_solo_deployment) must match the--networkflag you pass to Hardhat commands.
Step 4: Deploy and Interact with a Solidity Contract
The Sample Contract
If using the pre-built Solo example, contracts/SimpleStorage.sol is included.
For a new project, create contracts/SimpleStorage.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
contract SimpleStorage {
uint256 private value;
event ValueChanged(
uint256 indexed oldValue,
uint256 indexed newValue,
address indexed changer
);
constructor(uint256 initial) {
value = initial;
}
function get() external view returns (uint256) {
return value;
}
function set(uint256 newValue) external {
uint256 old = value;
value = newValue;
emit ValueChanged(old, newValue, msg.sender);
}
}
Compile the Contract
npx hardhat compile
Expected output:
Compiled 1 Solidity file successfully (evm target: paris).
Run the Tests
npx hardhat test --network my_solo_deployment
For the pre-built example, the test suite covers three scenarios:
SimpleStorage
✔ deploys with initial value
✔ updates value and emits ValueChanged event
✔ allows other accounts to set value
3 passing (12s)
Deploy via a Script
To deploy SimpleStorage to your Solo network using a deploy script:
npx hardhat run scripts/deploy.ts --network my_solo_deployment
A minimal scripts/deploy.ts looks like:
Hardhat v3: The bundled example pins Hardhat 3.x, which removed the
ethersnamed export from thehardhatmodule. Obtainethersfrom the network connection withconst { ethers } = await network.connect()instead ofimport { ethers } from "hardhat".
import { network } from "hardhat";
async function main() {
const { ethers } = await network.connect();
const SimpleStorage = await ethers.getContractFactory("SimpleStorage");
const contract = await SimpleStorage.deploy(42);
await contract.waitForDeployment();
console.log("SimpleStorage deployed to:", await contract.getAddress());
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
Step 5: Send a Transaction with ethers.js
To submit a transaction directly from a script using ethers.js via Hardhat:
import { network } from "hardhat";
async function main() {
const { ethers } = await network.connect();
const [sender] = await ethers.getSigners();
console.log("Sender:", sender.address);
const balance = await ethers.provider.getBalance(sender.address);
console.log("Balance:", ethers.formatEther(balance), "HBAR");
const tx = await sender.sendTransaction({
to: sender.address,
value: 10_000_000_000n,
});
await tx.wait();
console.log("Transaction confirmed. Hash:", tx.hash);
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
Run it with:
npx hardhat run scripts/send-tx.ts --network my_solo_deployment
Step 6: Use Foundry (forge and cast)
Foundry works with the Solo relay as well: forge create
and cast send submit transactions to the network, and forge test runs your
tests against a fork of it.
Version requirements: Foundry 1.8 or later, and Hiero JSON-RPC relay 0.80.0 or later (Solo 0.94.0 and later deploy relay 0.80.1). Foundry 1.8 sends EIP-1898 block parameters that older relay versions do not support.
Option A: Use the Pre-Built Solo Example
A ready-to-run Foundry project is provided in the Solo repository. It reuses the
SimpleStorage contract from Step 4:
git clone https://github.com/hiero-ledger/solo.git
cd solo/examples/foundry-with-solo
With a Solo network running, task test installs forge-std, deploys
SimpleStorage with forge create, updates it with cast send, and runs
forge test. To deploy the network as well, run task (see
Running the Full Example Automatically).
Option B: Configure Your Own Foundry Project
Point Foundry at the Solo relay in foundry.toml:
[profile.default]
src = "contracts"
out = "out"
libs = ["lib"]
evm_version = "cancun"
# Default RPC endpoint for forge and cast; forge test forks it.
eth_rpc_url = "http://localhost:37546"
# Solo networks are ephemeral and block numbers restart on every redeploy,
# so do not reuse cached fork state.
no_storage_caching = true
Install forge-std for the test helpers. Add --no-git when the project lives
inside another Git repository and you do not want a submodule:
forge install foundry-rs/forge-std
Deploy a Contract with forge create
forge build
forge create contracts/SimpleStorage.sol:SimpleStorage \
--rpc-url http://localhost:37546 \
--private-key "$SOLO_EVM_PRIVATE_KEY" \
--broadcast \
--constructor-args 42
--constructor-args takes every remaining argument, so keep it last. The output
includes a Deployed to: line with the contract address. Save it for the next
commands:
export SIMPLE_STORAGE_ADDRESS="0xYOUR_CONTRACT_ADDRESS"
Interact with the Contract Using cast
cast call "$SIMPLE_STORAGE_ADDRESS" "get()(uint256)" --rpc-url http://localhost:37546
cast send "$SIMPLE_STORAGE_ADDRESS" "set(uint256)" 7 \
--rpc-url http://localhost:37546 \
--private-key "$SOLO_EVM_PRIVATE_KEY"
cast call "$SIMPLE_STORAGE_ADDRESS" "get()(uint256)" --rpc-url http://localhost:37546
The first cast call returns 42 and the second returns 7.
Run forge test Against Solo
Because eth_rpc_url is set, forge test forks the Solo network: tests run in a
local EVM that loads accounts, code and storage from the relay on demand.
Contracts the tests create and the state changes they make stay in the fork and
never reach the Solo network. Use forge create or cast send to change the
network itself.
SIMPLE_STORAGE_VALUE=7 forge test -vvv
The example’s test/SimpleStorage.t.sol checks that the fork reports chain ID
298, runs the same three scenarios as the Hardhat tests, and reads the
SimpleStorage contract deployed above (from the exported
SIMPLE_STORAGE_ADDRESS) through the fork.
Note:
forge scriptis not covered. It has known limitations on Hedera when it broadcasts multiple transactions; useforge createandcast sendto change network state.
Step 7: Verify Transactions
Confirm your transactions reached consensus using any of the following:
Hiero Mirror Node Explorer
http://localhost:38080/localnet/dashboard
Note: If you are using Solo 0.62 or earlier, the Explorer is at
http://localhost:8080/localnet/dashboard.
Search by account address, transaction hash, or contract address to view transaction details and receipts.
Hiero Mirror Node REST API
http://localhost:38081/api/v1/transactions?limit=5
Returns the five most recent transactions in JSON format. Useful for scripted verification.
Note:
localhost:5551(the legacy Mirror Node REST API direct endpoint) is being phased out. Uselocalhost:38081(Solo 0.63+) orlocalhost:8081(Solo 0.62 and earlier) to ensure compatibility with all endpoints.
Hiero JSON RPC Relay (eth_getTransactionReceipt)
curl -X POST http://localhost:37546 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xYOUR_TX_HASH"],"id":1}'
Step 8: Configure MetaMask
To connect MetaMask to your local Solo network:
Open MetaMask and go to Settings → Networks → Add a network → Add a network manually.
Enter the following values:
Field Value Network name Solo LocalNew RPC URL http://localhost:37546Chain ID 298Currency symbol HBARNote: If you are using Solo 0.62 or earlier, use
http://localhost:7546for the RPC URL.Click Save and switch to the Solo Local network.
Import an account using an ECDSA private key from
accounts.json:- Click the account icon → Import account.
- Paste the private key (with
0xprefix). - Click Import.
Your MetaMask wallet is now connected to the local Solo network and funded with the pre-allocated HBAR balance.
Step 9: Tear Down the Network
When finished, destroy the Solo deployment and all associated containers:
npx @hiero-ledger/solo one-shot single destroy
If you added the relay manually to an existing deployment:
solo relay node destroy --deployment "${SOLO_DEPLOYMENT}"
Reference: Running the Full Example Automatically
The hardhat-with-solo example includes a Taskfile.yml that automates all
steps - deploy network, install dependencies, compile, and test - in a single
command:
cd solo/examples/hardhat-with-solo
task
To tear everything down:
task destroy
This is useful for CI pipelines. See the Solo deployment with Hardhat Example for full details.
The foundry-with-solo example does the same for Foundry - deploy the network,
install forge-std, deploy and update SimpleStorage with forge create and
cast send, then run forge test:
cd solo/examples/foundry-with-solo
task
Tear it down with task destroy. See the
Solo deployment with Foundry Example
for full details.
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
connection refused on port 37546 | Relay not running | Run one-shot single deploy or solo relay node add |
invalid sender or signature error | Using ED25519 key instead of ECDSA | Use ECDSA keys from accounts.json |
Hardhat chainId mismatch error | Missing or wrong chainId in config | Set chainId: 298 in hardhat.config.ts |
| MetaMask shows wrong network | Chain ID mismatch | Ensure Chain ID is 298 in MetaMask network settings |
INSUFFICIENT_TX_FEE on transaction | Account not funded | Use a pre-funded ECDSA account from accounts.json |
| Hardhat test timeout | Network not fully started | Wait for one-shot to fully complete before running tests |
forge test reports chain ID 31337 instead of 298 | forge test is not forking the relay | Set eth_rpc_url in foundry.toml or pass --fork-url http://localhost:37546 |
forge test fails while fetching state from the relay | Foundry 1.8+ against a relay older than 0.80.0 | Upgrade to Solo 0.94.0 or later (relay 0.80.1) |
forge create fails with contract was not deployed, but the contract exists | The deployment includes a block node: the mirror node then returns no created_contract_ids, so the relay receipt has no contractAddress (hiero-mirror-node#14473) | Deploy without a block node (ONE_SHOT_WITH_BLOCK_NODE=false) |
Port 37546 already in use | Another process is using the port | Run lsof -i :37546 and stop the conflicting process |
Further Reading
- Solo deployment with Hardhat Example.
- Solo deployment with Foundry Example.
- Foundry documentation - reference for
forge,cast, andfoundry.toml. - Configuring Hardhat with Hiero Local Node - the Hedera tutorial this guide is modelled on.
- Retrieving Logs - for debugging network-level issues.
3.5 - Using Network Load Generator with Solo
Using Network Load Generator with Solo
The Network Load Generator (NLG) is a benchmarking tool that stress tests Hiero networks by generating configurable transaction loads. Use it to validate the performance and stability of your Solo network before deploying to production or running integration tests.
Prerequisites
Before proceeding, ensure you have completed the following:
- System Readiness — your local environment meets all hardware and software requirements.
- Quickstart — you have a running Solo network and are familiar with the basic Solo workflow.
Step 1: Start a Load Test
Use the rapid-fire load start command to install the NLG Helm chart and
begin a load test against your deployment.
npx @hiero-ledger/solo@latest rapid-fire load start \
--deployment <deployment-name> \
--args '"-c 3 -a 10 -t 60"' \
--test CryptoTransferLoadTest
Replace <deployment-name> with your deployment name - find it with solo one-shot show deployment (see Capture your deployment name).
The --args flag passes arguments directly to the NLG. In this example:
- -c 3 — 3 concurrent threads
- -a 10 — 10 accounts
- -t 60 — run for 60 seconds
Step 2: Run Multiple Load Tests (Optional)
You can run additional load tests in parallel from a separate terminal. Each test runs independently against the same deployment:
npx @hiero-ledger/solo@latest rapid-fire load start \
--deployment <deployment-name> \
--args '"-c 3 -a 10 -t 60"' \
--test NftTransferLoadTest
Step 3: Stop a Specific Load Test
To stop a single running load test before it completes, use the stop command:
npx @hiero-ledger/solo@latest rapid-fire load stop \
--deployment <deployment-name> \
--test CryptoTransferLoadTest
Step 4: Tear Down All Load Tests
To stop all running load tests and uninstall the NLG Helm chart:
npx @hiero-ledger/solo@latest rapid-fire destroy all \
--deployment <deployment-name>
Complete Example
For an end-to-end walkthrough with a full configuration, see the examples/rapid-fire.
Available Tests and Arguments
A full list of all available rapid-fire commands can be found in Solo CLI Reference.
3.6 - Deploying a Local Consensus Node Build
Overview
Solo’s --local-build-path flag lets you deploy a network using a consensus
node binary you compiled locally. Use this when you need to:
- Test unreleased hiero-consensus-node code against a live Solo network.
- Reproduce a bug with a specific build.
- Iterate on platform changes without a full release cycle.
Solo validates the path for the expected apps/ and lib/ subdirectories,
then uses kubectl cp to push the local binaries directly into the running
node pods — no Docker image rebuild or registry push required.
Scope: This guide covers the consensus node local build workflow. Local build support for mirror node, block node, relay, and explorer requires additional engineering work and is not yet available as a first-class Solo feature.
Prerequisites
Solo CLI installed — if you have not yet deployed a network, follow the Quickstart first.
hiero-consensus-node cloned locally — see Step 1.
Java 25 (Temurin) — this is a hard Gradle toolchain requirement; Java 21 will fail with a cryptic toolchain error. Install with SDKMAN:
sdk install java 25.0.2-temGradle — the repository includes the Gradle wrapper (
./gradlew); no separate Gradle install is needed.
Step 1: Build hiero-consensus-node
Clone the repository and run ./gradlew assemble. This compiles the consensus
node and populates hedera-node/data/ with the runtime artifacts Solo needs:
hedera-node/data/lib/— runtime dependency JARshedera-node/data/apps/HederaNode.jar— the main consensus node binary
git clone https://github.com/hiero-ledger/hiero-consensus-node.git
cd hiero-consensus-node
./gradlew assemble
To build a specific release tag, use --branch:
git clone https://github.com/hiero-ledger/hiero-consensus-node.git \
--depth 1 --branch @<VERSION>
cd hiero-consensus-node
./gradlew assemble
Note: The initial Gradle build downloads dependencies and compiles all modules. Expect 10–30 minutes on a first run; subsequent incremental builds are faster.
Note: Solo copies
data/lib/anddata/apps/from your build path but skipsdata/config/anddata/keys/— those come from the container image. To customise consensus node configuration, see Custom Application Properties.
Step 2: Deploy with your local build
Choose the path that matches your situation.
Option A — New cluster (Falcon deploy)
Creates a fresh Kind cluster and deploys the full Solo network from scratch, using your local build for the consensus node.
Create a values file with the --local-build-path flag:
# local-build-values.yaml
setup:
--local-build-path: "/absolute/path/to/hiero-consensus-node/hedera-node/data"
Then deploy:
solo one-shot falcon deploy --values-file local-build-values.yaml
Use an absolute path — relative paths can behave unexpectedly depending on where Solo is invoked.
For a full deployment with mirror node, explorer, and relay, add the corresponding sections to your values file. See the One-Shot Falcon Deployment guide for the complete values file reference.
Option B — Existing cluster (consensus node setup)
If you already have a running Solo deployment and want to swap in a new consensus node binary without redeploying the whole network:
solo consensus node setup \
--deployment <deployment-name> \
--local-build-path /absolute/path/to/hiero-consensus-node/hedera-node/data
Replace <deployment-name> with your deployment name. One-shot deployments use
one-shot by default; You can see it with:
solo one-shot show deployment
Step 3: Verify the local build is running
Confirm that the consensus node gRPC port is reachable:
nc -zv localhost 35211
Expected output:
Connection to localhost port 35211 [tcp/*] succeeded!
Confirm that the pods are running your local build by inspecting the container images:
kubectl get pods -n <namespace> -o \
jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
Replace <namespace> with your deployment namespace (default: one-shot).
The consensus node pod should reference the image tag that matches your
--consensus-node-version (or the Solo built-in default if you omitted it). The key
indicator is that the node started successfully with your local data/lib/ and
data/apps/ artifacts copied in.
Step 4: Tear down
solo one-shot falcon destroy
Reference: ready-to-run example
The Solo repository ships a Task-based example that automates the full workflow — cloning at the correct versions, building the consensus node, generating an absolute-path values file, and deploying:
Download from the Solo releases page:
https://github.com/hiero-ledger/solo/releases/download/@<VERSION>/example-one-shot-local-build.zip
Run the full workflow with:
task
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
--local-build-path: path does not exist | ./gradlew assemble has not run, or the path is wrong | Confirm: ls /absolute/path/to/hiero-consensus-node/hedera-node/data/apps/HederaNode.jar |
./gradlew assemble fails with Unsupported class file major version | Wrong Java version | Check java -version; Java 25 (Temurin) is required. Install: sdk install java 25.0.2-tem |
| Consensus node pods crash on start | Build artifacts incompatible with the base container image | Set --consensus-node-version in your values file to match the source tag you built from |
nc -zv localhost 35211 fails after deploy | Port-forward died | Restore: kubectl port-forward svc/haproxy-node1-svc -n one-shot 35211:50211 & |
| Slow first deployment | Mirror node, relay, and explorer images pulling for the first time | Let it complete; subsequent runs reuse the image cache |
4 - Troubleshooting
This guide covers common issues you may encounter when using Solo and how to resolve them.
Quick Navigation
Use this page when something is failing and you need to diagnose or recover quickly.
- Error code reference
- Troubleshooting installation and upgrades
- Pods not reaching Ready state
- CrashLoopBackOff causes and remediation
- MinIO image pull failures (
ImagePullBackOffon the MinIO tenant pod) - Resource constraint errors (CPU / RAM / Disk)
- Getting help
Related Operational Topics
If you are looking for setup or day-to-day usage guidance rather than failure diagnosis, start with these pages:
- One-command deployment options and variants
- How to fully destroy a network and clean up resources
- How to access exposed services (mirror node, relay, explorer)
- Common usage patterns and gotchas
Error Code Reference
Every error Solo raises carries a structured code of the form SOLO-XXXX, an
ownership classification (User, Infrastructure, or Solo), and a retryable flag.
When a command fails with one of these codes, look it up in the
Error Codes reference for a plain-language
description of why it is thrown, along with its troubleshooting steps.
Codes are grouped by category — Configuration, Deployment, Component, Validation, System, and Internal. Solo’s CLI also prints a documentation link for each error (for example https://solo.hiero.org/docs/errors/SOLO-1001) that opens its page directly.
Anatomy of a Solo error
When a command fails with a coded error, Solo prints the code and message, suggested next steps, and a documentation link:
[SOLO-2002] A deployment named 'my-deployment' already exists. Please select a different name
→ Check existing deployments: solo deployment config list
→ Choose a different name for your deployment
Learn more: https://solo.hiero.org/docs/errors/SOLO-2002
- [SOLO-NNNN] is the error code; its leading digit identifies the category.
- → lines are suggested remediation steps, shown when the error provides them.
- Learn more links to that error’s online reference page.
In the terminal, this appears inside a bordered ERROR box, followed by a tip
suggesting solo deployment diagnostics logs or
solo deployment diagnostics report to gather more detail.
Note: Add
--debugto a command to see the full error cause chain and stack traces instead of the summarized form — useful when filing a bug report. (This flag was previously named--dev. The--devalias still works but is deprecated and will no longer be supported once Solo0.82.0reaches its end of support date.)
Common Issues and Solutions
Troubleshooting Installation and Upgrades
Installation and upgrade failures are common, especially when older installs or previous deployments are still present.
Symptoms
You are likely hitting an installation or upgrade problem if:
solofails to start after changing versions.solo one-shot single deployfails early with validation or environment errors.- Commands report missing dependencies or incompatible versions.
- A new deployment fails immediately after a previous network was not destroyed.
- A global install fails with
EEXIST: file already existspointing at.../bin/solo. This happens when Solo is already installed under the other npm package name (@hiero-ledger/soloand@hashgraph/soloare mirrors that share thesolobinary). See Resolving anEEXISTpackage-name conflict. - Topic messages fail with
FAIL_INVALIDaftersolo consensus network upgrade, while other transactions still succeed. See Topic messages fail withFAIL_INVALIDafter a network upgrade.
Quick Checks
Confirm installation method
If you previously installed Solo via Homebrew and are now migrating to npm, remove the Homebrew install to avoid conflicts:
brew uninstall hiero-ledger/tools/soloThen install via npm:
npm install -g @hiero-ledger/solo@latestIf you have Solo installed under both npm package names (
@hiero-ledger/soloand@hashgraph/solo), remove both before reinstalling:npm uninstall -g @hiero-ledger/solo || true npm uninstall -g @hashgraph/solo || trueIf a global npm install fails with
EEXISTbecause both package names are present, see Resolving anEEXISTpackage-name conflict.Verify system resources
Ensure your machine and Docker (or other container runtime) meet the minimum requirements described in
System readiness.If Docker Desktop or your container runtime is configured below these values, increase the allocations and retry the install or deploy.
Clean up previous deployments
If an upgrade or redeploy fails, first run a standard destroy:
solo one-shot single destroy
Pods not reaching Ready state
If pods remain in Pending, Init, ContainerCreating, or CrashLoopBackOff,
follow this sequence to identify the blocker.
Check readiness and restarts
# Show readiness and restart count for each pod kubectl get pods -n "${SOLO_NAMESPACE}" \ -o custom-columns=NAME:.metadata.name,PHASE:.status.phase,READY:.status.containerStatuses[*].ready,RESTARTS:.status.containerStatuses[*].restartCountInspect pod events
# List all pods in your namespace kubectl get pods -n "${SOLO_NAMESPACE}" # Describe a specific pod to see events kubectl describe pod -n "${SOLO_NAMESPACE}" <pod-name>Map symptoms to likely causes
Symptom Likely cause Next step PendingInsufficient resources Increase Docker memory/CPU allocation, then retry PendingStorage issues Check disk space, free space if needed, restart Docker CrashLoopBackOffContainer failing to start Check pod logs: kubectl logs -n "${SOLO_NAMESPACE}" <pod-name>ImagePullBackOffCan’t pull container images Check internet connectivity and Docker Hub rate limits. If the image is quay.io/minio/minio, see MinIO image pull failures
CrashLoopBackOff causes and remediation
If a pod repeatedly restarts and enters CrashLoopBackOff, inspect current
logs, previous logs, and events:
# Current container logs
kubectl logs -n "${SOLO_NAMESPACE}" <pod-name>
# Previous container logs (captures startup failures)
kubectl logs -n "${SOLO_NAMESPACE}" <pod-name> --previous
# Pod events and failure reasons
kubectl describe pod -n "${SOLO_NAMESPACE}" <pod-name>
Common causes include invalid runtime configuration, missing dependencies, and insufficient memory.
Recommended remediation sequence:
If events mention
OOMKilledor repeated liveness probe failures, increase Docker CPU/RAM and retry.If the issue started after a failed upgrade or deploy, run the cleanup steps in Old installation artifacts and redeploy.
If only one node is affected, refresh or restart it:
solo consensus node refresh --node-aliases node1 --deployment "${SOLO_DEPLOYMENT}" # or solo consensus node restart --deployment "${SOLO_DEPLOYMENT}"
Resource allocation:
- Ensure your machine and Docker (or other container runtime) meet the minimum requirements described in System readiness.
- On Docker Desktop, check: Settings > Resources.
MinIO image pull failures (ImagePullBackOff on the MinIO tenant pod)
MinIO stopped publishing new community-edition images as of 2025-10-23.
quay.io/minio/minio and docker.io/minio/minio now return 401 UNAUTHORIZED for every tag, including latest. Solo uses this image for the
MinIO tenant (the object storage backend for record streams and backups
deployed via the MinIO Operator), so any Solo deployment that enables MinIO
will fail with ImagePullBackOff on the tenant pod until the fix below is
applied.
Note: This affects Solo versions below v0.91.0. Starting with v0.91.0, Solo replaces the default tenant image so this workaround is no longer required. If you’re on an older version, use one of the two options below: skip MinIO entirely with environment variables (simplest), or override the tenant image with a values file if you need MinIO’s record-stream/backup storage.
Symptoms
kubectl get pods -n "${SOLO_NAMESPACE}" -l v1.min.io/tenant=minioshowsImagePullBackOfforErrImagePull.kubectl describe pod <minio-pool-pod> -n "${SOLO_NAMESPACE}"shows an event like:Failed to pull image "quay.io/minio/minio:RELEASE.2024-08-03T04-33-23Z": ... unexpected status from HEAD request ... 401 UNAUTHORIZEDA
one-shotornetwork deployrun hangs or fails on the “Deploy network node” step with[SOLO-3035] Pod readiness check failed ... for labels [v1.min.io/tenant=minio].
Easier option: skip MinIO entirely with environment variables
If you don’t need record-stream/backup storage and don’t want to deal with Helm values files, the simplest fix is to not deploy MinIO at all by running the network in native block-streaming mode instead:
export ONE_SHOT_WITH_BLOCK_NODE=true
export BLOCK_STREAM_STREAM_MODE=BLOCKS
solo one-shot single deploy
This works with one-shot single deploy (no need to switch to falcon)
because it’s a plain environment variable, not a CLI flag — Solo detects it and
skips the MinIO/record-uploader setup automatically. Use this unless you
specifically need the MinIO-backed record-stream/backup path; if you do, use
the values-file override below instead.
Workaround: override the tenant image with a values file
Point the MinIO tenant at a currently-available image using Solo’s
--values-file support. Silo is a MinIO fork
maintained by PGSTY that keeps publishing dated, S3-API-compatible images
after upstream stopped; its entrypoint transparently translates the MinIO
Operator’s server/minio invocation, so it’s a drop-in replacement here.
Create a plain Helm values file:
# minio-image-override.yaml
minio-server:
tenant:
image:
repository: docker.io/pgsty/silo@sha256
digest: 635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46
Then deploy with it:
solo network deploy -f ./minio-image-override.yaml
network deploy’s --values-file/-f passes this file straight to Helm, so
the plain values shape above is correct there.
If you are using one-shot instead
one-shot’s --values-file is a different shape — it is not a raw Helm
values file. Its top-level keys are per-command sections (network,
mirrorNode, relayNode, etc.), each holding --flag: value pairs that get
forwarded to the underlying command. To apply the same override through
one-shot, nest the Helm values file above inside a network section:
# falcon-values.yaml
network:
--values-file: ./minio-image-override.yaml
solo one-shot falcon deploy --values-file ./falcon-values.yaml
one-shot single deploy does not accept --values-file at all — the flag
is only registered on one-shot falcon deploy. If your existing workflow uses
solo one-shot single deploy, switch it to solo one-shot falcon deploy
(same underlying deploy pipeline, single is just a preset without the
values-file escape hatch) to apply this workaround.
Topic messages fail with FAIL_INVALID after a network upgrade
A consensus node keeps its fee schedule in system file 0.0.113. The file is
created once and is only replaced when an upgrade supplies a new copy, which
solo consensus network upgrade does not do by default. Consensus node
v0.72.x creates the file without the per-byte entry for topic messages, and
v0.73.0 and later require that entry. A network whose fee file was created
by v0.72.x therefore rejects every topic message after it is upgraded to v0.73.0
or later.
You are affected if your network ran v0.72.x at some point, either deployed on it or upgraded through it, and was later upgraded to v0.73.0 or later. Networks deployed on v0.73.0 or later, and networks upgraded directly from v0.71.x or earlier, get a complete fee file and are not affected.
Symptoms
TopicMessageSubmitTransactionfails at precheck withFAIL_INVALIDon every node. Other transactions, includingTopicCreateTransactionand transfers, still succeed.The consensus node log contains:
kubectl exec network-node1-0 -n "${SOLO_NAMESPACE}" -c root-container -- \ grep -h "Extra not defined" /opt/hgcapp/services-hedera/HapiApp2.0/output/hgcaa.logERROR IngestWorkflowImpl - Possibly CATASTROPHIC failure while running the ingest workflow java.lang.IllegalArgumentException: Extra not defined CONSENSUS_SUBMIT_MESSAGE_WITHOUT_CUSTOM_FEE_BYTES
Fix: upgrade with the target version’s fee schedule
Upgrade the network to a newer consensus node version and pass that version’s
simpleFeesSchedules.json with --simple-fees-schedules-file. Solo applies the
file on every node as part of the upgrade.
Download the fee schedule for the version you are upgrading to. It must come from that exact release tag:
export TARGET_VERSION=v0.76.4 curl -fsSL -o simpleFeesSchedules.json \ "https://raw.githubusercontent.com/hiero-ledger/hiero-consensus-node/${TARGET_VERSION}/hedera-node/configuration/mainnet/upgrade/simpleFeesSchedules.json"Upgrade with the file:
solo consensus network upgrade --deployment "${SOLO_DEPLOYMENT}" \ --upgrade-version "${TARGET_VERSION}" \ --simple-fees-schedules-file ./simpleFeesSchedules.jsonConfirm every node applied the file:
kubectl exec network-node1-0 -n "${SOLO_NAMESPACE}" -c root-container -- \ grep -h "Dispatching synthetic update" /opt/hgcapp/services-hedera/HapiApp2.0/output/hgcaa.logThe output should include a line ending in
data/config/simpleFeesSchedules.json. The node applies the file on the first transaction after the restart, so wait a few seconds if the line is not there yet.
Note: The file is applied only during an upgrade to a newer consensus node version. Re-running an upgrade to the version the network already runs does not apply it. The flag requires Solo v0.XX.0 or later and a target version of v0.68.0 or later, and it cannot be combined with
--upgrade-zip-file. See Apply updated fee schedules and throttles for details.
Resource constraint errors (CPU / RAM / Disk)
Resource pressure is a common cause of Pending pods, slow startup, and
repeated restarts.
Check Kubernetes-level CPU and memory utilization:
kubectl top nodes kubectl top pods -n "${SOLO_NAMESPACE}"Check host and Docker disk usage:
# Host disk availability df -h # Docker disk usage (if using Docker) docker system dfCompare against the recommended local baseline:
See System readiness for the recommended memory, CPU, and disk values.
JSON-RPC Relay Out of Memory
If the relay or relay-ws pods are being killed (OOMKilled) or restarting due
to memory pressure, the sections below explain why this happens and how to
resolve it.
Understanding the default memory configuration
Solo ships with a default memory limit of 88Mi and an explicit V8 old-space
cap of 66MB (--max-old-space-size=66) for both the relay and WebSocket
services. These values are tuned for the one-shot development profile and may
not be sufficient for heavy workloads.
How Node.js memory works in containers
Since Node.js 12.7.0, Node.js reads the Linux cgroup memory limit set by Kubernetes to determine the V8 old-space heap size, rather than using the host’s physical memory. Based on V8’s internal heap sizing heuristics, this tends to be roughly ~50% of the container memory limit on 64-bit systems, though the exact value depends on V8 internals and varies at both ends of the memory spectrum.
A couple of things to be aware of:
- cgroup v2 environments: many modern Linux distributions enable cgroup v2 by default, and Kubernetes 1.25 brought cgroup v2 support to GA. Older Node.js versions may not correctly detect the container limit under cgroup v2 and could silently fall back to the host’s physical memory, allocating a much larger heap than intended. This was improved in at least Node.js 20.3.0, which upgraded libuv to 1.45.0.
- When
--max-old-space-sizeis explicitly set (as in Solo’s default config), it overrides the auto-sizing entirely — the cgroup-based detection only kicks in when no explicit value is provided.
This means:
- If you increase only the pod memory limit (e.g., to 256Mi) but leave
NODE_OPTIONSunchanged, old space stays at 66 MB. - If you remove
NODE_OPTIONS, Node.js will attempt to auto-size old space based on the container limit (roughly ~128 MB for a 256Mi pod on a modern Node.js version).
Adjusting memory for heavier workloads
Create a custom values file (e.g., custom-relay-values.yaml) and pass it when
deploying:
# Option 1: Explicit old-space control (recommended for precise tuning)
relay:
resources:
limits:
memory: 256Mi
config:
NODE_OPTIONS: '--max-old-space-size=192'
ws:
resources:
limits:
memory: 256Mi
config:
NODE_OPTIONS: '--max-old-space-size=192'
# Option 2: Let Node.js auto-detect (simpler, old space ≈ 50% of limit)
# relay:
# resources:
# limits:
# memory: 256Mi
# config:
# NODE_OPTIONS: ""
# ws:
# resources:
# limits:
# memory: 256Mi
# config:
# NODE_OPTIONS: ""
Then deploy or upgrade with:
solo relay node add --deployment "${SOLO_DEPLOYMENT}" --values-file custom-relay-values.yaml
# or
solo relay node upgrade --deployment "${SOLO_DEPLOYMENT}" --values-file custom-relay-values.yaml
Connection refused errors
If you cannot connect to Solo network endpoints from your machine, use this sequence to isolate the issue.
Verify services and endpoints inside the cluster
# List all services kubectl get svc -n "${SOLO_NAMESPACE}" # Check if endpoints are populated kubectl get endpoints -n "${SOLO_NAMESPACE}"- If the service exists but has no endpoints, the backing pods are not
Ready.
See Pods not reaching Ready state.
- If the service exists but has no endpoints, the backing pods are not
Ready.
Use manual port forwarding (bypass automation)
If automatic port forwarding (from
solocommands or your environment) is not working, forward the required services manually. The local ports below match the Solo 0.63+ defaults — adjust to any available port if needed:# Consensus node (gRPC) — local port 35211 → service port 50211 kubectl port-forward svc/haproxy-node1-svc -n "${SOLO_NAMESPACE}" 35211:50211 & # Explorer UI — local port 38080 → service port 8080 kubectl port-forward svc/hiero-explorer -n "${SOLO_NAMESPACE}" 38080:8080 & # Mirror node ingress (REST API) — local port 38081 → service port 80 kubectl port-forward svc/mirror-1-rest -n "${SOLO_NAMESPACE}" 38081:80 & # Mirror node gRPC kubectl port-forward svc/mirror-1-grpc -n "${SOLO_NAMESPACE}" 5600:5600 & # JSON-RPC relay — local port 37546 → service port 7546 kubectl port-forward svc/relay-node1-hedera-json-rpc-relay -n "${SOLO_NAMESPACE}" 37546:7546 &Note: For Solo 0.62 and earlier, use local ports
50211,8080,5551, and7546respectively.Confirm the expected endpoints and ports
After forwarding, connect to the local ports shown above (for example,
http://localhost:38080for the explorer).
For the standard exposed endpoints after a successful one-shot deployment, see How to access exposed services (mirror node, relay, explorer).
Node synchronization issues
If nodes are not forming consensus or transactions are not being processed, follow these steps.
Check node state and gossip logs:
# Download state information for a node solo consensus state download --deployment "${SOLO_DEPLOYMENT}" --node-aliases node1 # Check logs for gossip-related issues kubectl logs -n "${SOLO_NAMESPACE}" network-node-0 | grep -i gossipLook for repeated connection failures, timeouts, or gossip disconnection messages.
Restart problematic nodes:
# Refresh a specific node solo consensus node refresh --node-aliases node1 --deployment "${SOLO_DEPLOYMENT}" # Or restart all nodes solo consensus node restart --deployment "${SOLO_DEPLOYMENT}"After restarting, submit a small test transaction and verify that it reaches consensus.
Mirror node not importing records
If the mirror node is not showing new transactions, first confirm that records are being generated and imported.
Verify the pinger is running
The
--pingerflag should be enabled when deploying the mirror node. The pinger sends periodic transactions so that record files are created.# Check if pinger pod is running kubectl get pods -n "${SOLO_NAMESPACE}" | grep pingerRedeploy the mirror node with pinger enabled
If the pinger is missing or misconfigured:
# Destroy the existing mirror node solo mirror node destroy --deployment "${SOLO_DEPLOYMENT}" --force # Redeploy with pinger enabled solo mirror node add \ --deployment "${SOLO_DEPLOYMENT}" \ --cluster-ref kind-${SOLO_CLUSTER_NAME} \ --enable-ingress \ --pinger
Helm repository errors
If you see errors such as repository name already exists, you likely have a
conflicting Helm repo entry.
List current Helm repositories:
helm repo listRemove the conflicting repository:
helm repo remove <repo-name> # Example: remove hedera-json-rpc-relay helm repo remove hedera-json-rpc-relay
Re-run the Solo command that configures Helm after removing the conflict.
Kind cluster issues
Problems starting or accessing the Kind cluster often present as cluster creation failures or missing nodes.
Cluster will not start or is in a bad state:
# Delete and recreate the cluster kind delete cluster -n "${SOLO_CLUSTER_NAME}" kind create cluster -n "${SOLO_CLUSTER_NAME}"Docker context or daemon issues
Ensure Docker is running and the correct context is active:
# Check Docker is running docker ps # On macOS/Windows, ensure Docker Desktop is started. # On Linux, ensure the Docker daemon is running: sudo systemctl start docker
Cleanup and reset (old installation artifacts)
Previous Solo installations can cause conflicts during new deployments.
For the full teardown and full reset procedure, see the
Cleanup guide.
At a high level:
Run a standard destroy first:
solo one-shot single destroyIf
destroyfails or Solo state is corrupted, perform a full reset, which:- Deletes Solo-managed Kind clusters (names starting with
solo). - Removes the Solo home directory (
~/.solo).
- Deletes Solo-managed Kind clusters (names starting with
Windows (PowerShell) issues
These issues are specific to running Solo natively from Windows PowerShell.
Paths use backslashes. Solo stores its files under $env:USERPROFILE\.solo
on Windows - the equivalent of ~/.solo on macOS and Linux. When you copy a
command that uses ~/.solo/..., replace it with $env:USERPROFILE\.solo\....
For example:
Get-Content $env:USERPROFILE\.solo\logs\solo.log -Wait -Tail 50
Environment variable syntax differs. PowerShell does not use export. Set a
variable for the current session, or persist it for your user:
# Current session only
$env:SOLO_LOG_LEVEL = 'debug'
# Persist for your user (all future sessions)
[System.Environment]::SetEnvironmentVariable('SOLO_LOG_LEVEL', 'debug', 'User')
Removing a variable from the current session. Use Remove-Item on the
Env: drive. Setting $env:VAR = '' only blanks the value; it does not remove
the variable:
Remove-Item Env:\SOLO_LOG_LEVEL
Port-forwarding fails with listen EACCES. On Windows this is usually a
WinNAT reserved-port-range conflict. Solo automatically restarts the WinNAT
service and retries the port-forward. If the problem persists, restart WinNAT
manually from an elevated PowerShell prompt:
net stop winnat
net start winnat
Collecting diagnostic information
Before seeking help, collect the following diagnostics so issues can be reproduced and analyzed.
Solo diagnostics
Capture comprehensive diagnostics for the deployment:
solo deployment diagnostics all --deployment "${SOLO_DEPLOYMENT}"This creates logs and diagnostic files under
~/.solo/logs/.
Key log files
These files are often requested when reporting issues:
| File | Description |
|---|---|
~/.solo/logs/solo.log | Solo CLI command logs (human-readable, pino-pretty) |
~/.solo/logs/solo.ndjson | Solo CLI command logs (machine-readable JSON, for jq) |
Kubernetes diagnostics
Collect basic cluster and namespace information:
# Cluster info
kubectl cluster-info
# All resources in the Solo namespace
kubectl get all -n "${SOLO_NAMESPACE}"
# Recent events in the namespace (sorted by time)
kubectl get events -n "${SOLO_NAMESPACE}" --sort-by='.lastTimestamp'
# Node and pod resource usage
kubectl top nodes
kubectl top pods -n "${SOLO_NAMESPACE}"
Getting Help
1. Check the Logs
Always start by examining logs:
# Solo logs
cat ~/.solo/logs/solo.log | tail -100
# Pod logs
kubectl logs -n "${SOLO_NAMESPACE}" <pod-name>
2. Documentation
- Quickstart - Basic setup and usage.
- Advanced Solo Setup - Complex deployment scenarios.
- FAQs - Common questions and answers.
- Solo CLI Reference - Canonical command and flag reference.
- Error Codes reference - Look up any
SOLO-XXXXerror code.
3. GitHub Issues
Report bugs or request features:
- Repository: https://github.com/hiero-ledger/solo/issues
When opening an issue, include:
- Solo version (
solo --version) - Operating system and version
- Docker/Kubernetes versions
- Steps to reproduce the issue
- Relevant log output
- Any error messages
4. Community Support
Join the community for discussions and help:
- Hedera Discord: Look for the
#solochannel - Contribute to Hiero: https://hiero.org/#contribute
4.1 - Error Codes
All Solo errors carry a structured code, an ownership classification, and troubleshooting steps. Click an error code to see its dedicated page.
Exit codes
| Exit code | Meaning |
|---|---|
0 | The command completed. |
1 | The command failed for a reason other than its input, for example a failed deployment. |
2 | The input was rejected: a command-line usage error, or a failure whose root cause is a Validation error with User ownership, such as an unsupported component version combination. |
Configuration
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-1001 | LocalConfigNotFoundSoloError | User | No |
| SOLO-1002 | WriteLocalConfigFileError | Infrastructure | No |
| SOLO-1003 | RefreshLocalConfigSourceError | Infrastructure | No |
| SOLO-1004 | RemoteConfigsMismatchSoloError | Infrastructure | No |
| SOLO-1005 | IncompleteLocalConfigError | Infrastructure | No |
| SOLO-1006 | RemoteConfigDataInvalidSoloError | Infrastructure | No |
| SOLO-1007 | MigrateLegacyLocalConfigError | Infrastructure | No |
| SOLO-1008 | RemoteConfigMissingOnKindClusterError | User | No |
| SOLO-1009 | RemoteConfigMissingForDeployError | User | No |
Deployment
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-2001 | CreateDeploymentSoloError | Infrastructure | Yes |
| SOLO-2002 | DeploymentAlreadyExistsSoloError | User | No |
| SOLO-2003 | DeploymentNotFoundError | User | No |
| SOLO-2004 | DeploymentHasRemoteResourcesError | User | No |
| SOLO-2005 | DeploymentDeleteFailedError | Infrastructure | Yes |
| SOLO-2006 | ClusterAddFailedError | Infrastructure | No |
| SOLO-2007 | DeploymentListFailedError | Infrastructure | Yes |
| SOLO-2008 | ClusterReferenceNotFoundError | User | No |
| SOLO-2009 | ClusterReferenceAlreadyExistsError | User | No |
| SOLO-2010 | NamespaceNotSetError | User | No |
| SOLO-2011 | NoClustersForDeploymentError | User | No |
| SOLO-2012 | ClusterReferenceResolutionFailedError | Solo | No |
| SOLO-2013 | ContextNotFoundForClusterError | User | No |
| SOLO-2014 | NoDeploymentsFoundError | User | No |
| SOLO-2015 | DeploymentListPortsFailedError | Infrastructure | Yes |
| SOLO-2016 | ClusterSetupFailedSoloError | Infrastructure | No |
| SOLO-2017 | ClusterResetFailedSoloError | Infrastructure | No |
| SOLO-2018 | MinioInstallFailedSoloError | Infrastructure | No |
| SOLO-2019 | PrometheusInstallFailedSoloError | Infrastructure | No |
| SOLO-2020 | MetricsServerInstallFailedSoloError | Infrastructure | No |
| SOLO-2021 | ClusterRoleInstallFailedSoloError | Infrastructure | No |
| SOLO-2022 | ClusterApiServerTimeoutSoloError | Infrastructure | Yes |
| SOLO-2023 | KindClusterNetworkSetupFailedSoloError | Infrastructure | No |
| SOLO-2024 | BackupExportFailedSoloError | Infrastructure | No |
| SOLO-2025 | BackupImportFailedSoloError | Infrastructure | No |
| SOLO-2026 | BackupRestoreClustersFailedSoloError | Infrastructure | No |
| SOLO-2027 | DeployNetworkFailedSoloError | Infrastructure | No |
| SOLO-2029 | BlockNodeClusterContextNotFoundSoloError | User | No |
| SOLO-2030 | MirrorNodeClusterContextNotFoundSoloError | User | No |
| SOLO-2031 | DeploymentImportFailedSoloError | Infrastructure | Yes |
| SOLO-2033 | NetworkAlreadyDeployedSoloError | User | No |
| SOLO-2034 | GrafanaAlloyInstallFailedSoloError | Infrastructure | No |
| SOLO-2035 | LokiInstallFailedSoloError | Infrastructure | No |
Component
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-3001 | NodeTransactionFailedSoloError | Infrastructure | No |
| SOLO-3003 | NodeBuildUploadFailedSoloError | Infrastructure | Yes |
| SOLO-3004 | NodeBuildCopyFailedSoloError | Infrastructure | Yes |
| SOLO-3005 | NodeJfrExecutionFailedSoloError | Infrastructure | Yes |
| SOLO-3006 | NodeJfrPidNotFoundSoloError | Solo | No |
| SOLO-3007 | NodeDebugArchiveFailedSoloError | Solo | No |
| SOLO-3008 | BlockNodeConfigFailedSoloError | Infrastructure | Yes |
| SOLO-3009 | ChartInstallFailedSoloError | Infrastructure | Yes |
| SOLO-3010 | NetworkDestroyFailedSoloError | Infrastructure | No |
| SOLO-3011 | NodeNotReadySoloError | Infrastructure | No |
| SOLO-3012 | RapidFireExecutionSoloError | Infrastructure | Yes |
| SOLO-3013 | NodeStakeTransactionErrorSoloError | Infrastructure | Yes |
| SOLO-3014 | NodePrepareUpgradeTransactionErrorSoloError | Infrastructure | Yes |
| SOLO-3015 | NodeFreezeUpgradeTransactionErrorSoloError | Infrastructure | Yes |
| SOLO-3016 | NodeFreezeTransactionErrorSoloError | Infrastructure | Yes |
| SOLO-3017 | NodeUpdateTransactionErrorSoloError | Infrastructure | No |
| SOLO-3018 | NodeDeleteTransactionErrorSoloError | Infrastructure | No |
| SOLO-3019 | NodeCreateTransactionErrorSoloError | Infrastructure | No |
| SOLO-3021 | AccountBalanceQueryFailedSoloError | Infrastructure | Yes |
| SOLO-3022 | ExplorerDeployFailedSoloError | Infrastructure | No |
| SOLO-3023 | ExplorerUpgradeFailedSoloError | Infrastructure | No |
| SOLO-3024 | ExplorerDestroyFailedSoloError | Infrastructure | No |
| SOLO-3025 | RelayDeployFailedSoloError | Infrastructure | No |
| SOLO-3026 | RelayUpgradeFailedSoloError | Infrastructure | No |
| SOLO-3027 | RelayDestroyFailedSoloError | Infrastructure | No |
| SOLO-3028 | RelayNotRunningSoloError | Infrastructure | Yes |
| SOLO-3029 | RelayNotReadySoloError | Infrastructure | Yes |
| SOLO-3030 | RelayOperatorKeyRetrievalFailedSoloError | Infrastructure | Yes |
| SOLO-3031 | MirrorNodeDeployFailedSoloError | Infrastructure | No |
| SOLO-3032 | MirrorNodeUpgradeFailedSoloError | Infrastructure | No |
| SOLO-3033 | MirrorNodeDestroyFailedSoloError | Infrastructure | No |
| SOLO-3034 | MirrorNodeOperatorKeyRetrievalFailedSoloError | Infrastructure | Yes |
| SOLO-3035 | OneShotDeployFailedSoloError | Infrastructure | No |
| SOLO-3036 | OneShotDestroyFailedSoloError | Infrastructure | No |
| SOLO-3037 | OneShotDeploymentInfoRetrievalFailedSoloError | Infrastructure | No |
| SOLO-3038 | FalconValuesPreparationFailedSoloError | Infrastructure | No |
| SOLO-3039 | BlockNodeDeployFailedSoloError | Infrastructure | No |
| SOLO-3040 | BlockNodeDestroyFailedSoloError | Infrastructure | No |
| SOLO-3041 | BlockNodeUpgradeFailedSoloError | Infrastructure | No |
| SOLO-3042 | BlockNodeAddExternalFailedSoloError | Infrastructure | No |
| SOLO-3043 | BlockNodeDeleteExternalFailedSoloError | Infrastructure | No |
| SOLO-3044 | BlockNodeHealthCheckFailedSoloError | Infrastructure | Yes |
| SOLO-3045 | RapidFireLoadStartFailedSoloError | Infrastructure | Yes |
| SOLO-3046 | RapidFireLoadStopFailedSoloError | Infrastructure | No |
| SOLO-3047 | RapidFireKillFailedSoloError | Infrastructure | No |
| SOLO-3048 | AccountCreationFailedSoloError | Infrastructure | No |
| SOLO-3049 | AccountKeyUpdateFailedSoloError | Infrastructure | No |
| SOLO-3050 | AccountKeysBatchUpdateFailedSoloError | Infrastructure | No |
| SOLO-3051 | AccountTransferFailedSoloError | Infrastructure | No |
| SOLO-3052 | AccountInfoFailedSoloError | Infrastructure | No |
| SOLO-3053 | AccountUpdateFailedSoloError | Infrastructure | No |
| SOLO-3054 | AccountSecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3055 | EvmAddressRetrievalFailedSoloError | Infrastructure | No |
| SOLO-3056 | NodeAccessConfigFailedSoloError | Infrastructure | No |
| SOLO-3057 | NodeClientLoadFailedSoloError | Infrastructure | No |
| SOLO-3058 | NodeClientRefreshFailedSoloError | Infrastructure | No |
| SOLO-3059 | NodeClientSetupFailedSoloError | Infrastructure | No |
| SOLO-3060 | SdkPingFailedSoloError | Infrastructure | Yes |
| SOLO-3061 | NodeServicesRetrievalFailedSoloError | Infrastructure | No |
| SOLO-3062 | GossipKeySecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3063 | TlsKeySecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3064 | TlsKeyGenerationFailedSoloError | Infrastructure | No |
| SOLO-3065 | SigningKeyGenerationFailedSoloError | Infrastructure | No |
| SOLO-3066 | GrpcTlsKeyGenerationFailedSoloError | Infrastructure | No |
| SOLO-3067 | GrpcTlsCertMismatchSoloError | User | No |
| SOLO-3068 | GrpcWebTlsCertMismatchSoloError | User | No |
| SOLO-3069 | CertificateSecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3070 | CertificateParsingFailedSoloError | User | No |
| SOLO-3071 | CertificateFileNotFoundSoloError | User | No |
| SOLO-3072 | ExplorerTlsSecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3073 | PlatformFileNotFoundSoloError | Infrastructure | No |
| SOLO-3074 | PlatformFileCopyFailedSoloError | Infrastructure | No |
| SOLO-3075 | PlatformKeyFileMissingSoloError | Infrastructure | No |
| SOLO-3076 | GenesisAdminKeySecretFailedSoloError | Infrastructure | No |
| SOLO-3077 | GenesisDataGenerationFailedSoloError | Infrastructure | No |
| SOLO-3078 | PostgresInitScriptCopyFailedSoloError | Infrastructure | No |
| SOLO-3079 | PostgresInitScriptFailedSoloError | Infrastructure | Yes |
| SOLO-3080 | MirrorPasswordSecretMissingSoloError | Infrastructure | No |
| SOLO-3081 | FileContentVerificationFailedSoloError | Infrastructure | No |
| SOLO-3082 | HederaFileCreationFailedSoloError | Infrastructure | No |
| SOLO-3083 | HederaFileUpdateFailedSoloError | Infrastructure | No |
| SOLO-3084 | HederaFileAppendFailedSoloError | Infrastructure | No |
| SOLO-3085 | NodeStatusEmptyResponseSoloError | Infrastructure | No |
| SOLO-3086 | NodeStatusMissingLineSoloError | Infrastructure | No |
| SOLO-3087 | PredefinedAccountsCreationFailedSoloError | Infrastructure | No |
| SOLO-3088 | FileContentMismatchSoloError | Infrastructure | No |
| SOLO-3089 | NodeServiceNotFoundSoloError | User | No |
| SOLO-3090 | BlockNodeJfrCollectionFailedSoloError | Infrastructure | Yes |
| SOLO-3091 | GossipKeySecretRestoreFailedSoloError | Infrastructure | No |
| SOLO-3092 | SdkClientNoHealthyNodesSoloError | Infrastructure | Yes |
| SOLO-3093 | NodeKeyLoadFailedSoloError | User | No |
| SOLO-3094 | NodeContainerCrashedSoloError | Infrastructure | No |
| SOLO-3095 | RelayOperatorSecretCreationFailedSoloError | Infrastructure | No |
| SOLO-3096 | MirrorNodeJfrCollectionFailedSoloError | Infrastructure | Yes |
| SOLO-3097 | NodeRestoreStatusMismatchSoloError | User | No |
| SOLO-3098 | NodeAdminKeySaveFailedSoloError | Infrastructure | No |
Validation
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-4001 | MissingArgumentError | User | No |
| SOLO-4002 | IllegalArgumentError | User | No |
| SOLO-4003 | InvalidOutputFormatError | User | No |
| SOLO-4004 | ConsensusNodeCountRequiredError | User | No |
| SOLO-4005 | InvalidPortNumberError | User | No |
| SOLO-4006 | LocalBuildPathNotFoundSoloError | User | No |
| SOLO-4007 | LocalBuildMissingSubdirectoriesSoloError | User | No |
| SOLO-4008 | LocalBuildNoJarFilesSoloError | User | No |
| SOLO-4009 | NodeJarFilesNotInContainerSoloError | Solo | No |
| SOLO-4010 | GrpcEndpointsRequiredSoloError | User | No |
| SOLO-4011 | OutputDirectoryNotSpecifiedSoloError | User | No |
| SOLO-4012 | InputDirectoryNotSpecifiedSoloError | User | No |
| SOLO-4013 | WrapsKeyPathNotFoundSoloError | User | No |
| SOLO-4014 | ConfigFileNotFoundSoloError | User | No |
| SOLO-4015 | NodeVersionMismatchSoloError | User | No |
| SOLO-4016 | UpgradeVersionNotFoundSoloError | User | No |
| SOLO-4017 | PvcFlagNotEnabledSoloError | User | No |
| SOLO-4018 | NonInteractivePromptSoloError | User | No |
| SOLO-4020 | WrapsVersionConstraintSoloError | User | No |
| SOLO-4021 | StateFilePathNotFoundSoloError | User | No |
| SOLO-4022 | StateFileNotFoundSoloError | User | No |
| SOLO-4023 | InvalidStateFileFormatSoloError | User | No |
| SOLO-4024 | InvalidStateZipFileNameSoloError | User | No |
| SOLO-4025 | ExplorerInvalidComponentIdSoloError | User | No |
| SOLO-4026 | RelayInvalidComponentIdSoloError | User | No |
| SOLO-4028 | MirrorNodeInvalidComponentIdSoloError | User | No |
| SOLO-4029 | BlockNodeLocalImageNotFoundSoloError | User | No |
| SOLO-4030 | BlockNodeInvalidComponentIdSoloError | Solo | No |
| SOLO-4033 | InvalidHbarAmountSoloError | User | No |
| SOLO-4034 | InvalidFileIdFormatSoloError | User | No |
| SOLO-4035 | InvalidEndpointFormatSoloError | User | No |
| SOLO-4036 | InvalidCommaSeparatedStringSoloError | User | No |
| SOLO-4037 | InvalidConfigNumberValueSoloError | User | No |
| SOLO-4038 | InvalidStorageTypeSoloError | User | No |
| SOLO-4039 | UnsupportedFlagFieldTypeSoloError | Solo | No |
| SOLO-4040 | VersionDowngradeBlockedSoloError | User | No |
| SOLO-4041 | AdminKeysCountMismatchSoloError | User | No |
| SOLO-4042 | ComponentAlreadyExistsSoloError | Solo | No |
| SOLO-4043 | ComponentIdRequiredSoloError | Solo | No |
| SOLO-4044 | ComponentNotFoundSoloError | Solo | No |
| SOLO-4045 | ComponentNotInRemoteConfigSoloError | Solo | No |
| SOLO-4046 | UnknownComponentTypeSoloError | Solo | No |
| SOLO-4047 | ConfigFileInvalidSoloError | User | No |
| SOLO-4048 | MultipleClustersFoundSoloError | User | No |
| SOLO-4049 | CacheNotMaterializedSoloError | User | No |
| SOLO-4050 | CacheImageTemplateUnknownSoloError | User | No |
| SOLO-4052 | PathTraversalDetectedSoloError | User | No |
| SOLO-4053 | NodeAliasesMustBeArraySoloError | Solo | No |
| SOLO-4054 | UnknownNodeAliasSoloError | User | No |
| SOLO-4055 | NodeAliasInferenceFailedSoloError | User | No |
| SOLO-4056 | NodeAliasParseFailedSoloError | User | No |
| SOLO-4057 | DomainNameParseFailedSoloError | User | No |
| SOLO-4058 | UnknownTemplateDependencySoloError | Solo | No |
| SOLO-4059 | NoConsensusNodesFoundSoloError | User | No |
| SOLO-4060 | ServiceTypeMismatchSoloError | Infrastructure | No |
| SOLO-4061 | BackupConfigNotFoundSoloError | User | No |
| SOLO-4062 | BackupConfigInvalidSoloError | User | No |
| SOLO-4063 | BackupConfigReadFailedSoloError | Infrastructure | No |
| SOLO-4064 | BackupConfigMapKeyMissingSoloError | Infrastructure | No |
| SOLO-4065 | BackupConfigParseFailedSoloError | Infrastructure | No |
| SOLO-4066 | BackupInputDirectoryNotFoundSoloError | User | No |
| SOLO-4067 | BackupNoClusterDirectoriesSoloError | User | No |
| SOLO-4068 | BackupClusterValidationFailedSoloError | User | No |
| SOLO-4069 | BackupNoClusterInfoSoloError | User | No |
| SOLO-4070 | BackupNoComponentsSoloError | User | No |
| SOLO-4071 | BackupOptionsFileNotFoundSoloError | User | No |
| SOLO-4072 | BackupZipFileRequiredSoloError | User | No |
| SOLO-4073 | BackupInputPathNotFoundSoloError | User | No |
| SOLO-4074 | BackupInputMustBeZipSoloError | User | No |
| SOLO-4075 | BackupNoLogFilesSoloError | User | No |
| SOLO-4076 | FlagInputFailedSoloError | User | No |
| SOLO-4077 | ConfirmationRequiredSoloError | User | No |
| SOLO-4078 | ValuesFileNotFoundSoloError | User | No |
| SOLO-4079 | ValuesFileParseFailedSoloError | User | No |
| SOLO-4080 | BackupDatabaseDumpNotFoundSoloError | User | No |
| SOLO-4081 | InvalidFlagValueSoloError | User | No |
| SOLO-4082 | TransplantRequiresStateFileSoloError | User | No |
| SOLO-4083 | ComponentVersionIncompatibleSoloError | User | No |
| SOLO-4084 | ComponentImageArchiveTagMismatchSoloError | User | No |
| SOLO-4085 | SubprocessConfigLoadFailedSoloError | User | No |
| SOLO-4086 | SubprocessConfigUnsafePermissionsSoloError | User | No |
| SOLO-4087 | SubprocessConfigInvalidValueSoloError | User | No |
| SOLO-4088 | UpgradeSystemFileWithZipFileSoloError | User | No |
| SOLO-4089 | PostUpgradeSystemFileVersionUnsupportedSoloError | User | No |
| SOLO-4090 | ComponentUpgradeRequiresRedeploySoloError | User | No |
| SOLO-4091 | InvalidNetworkNodeLifecycleModeSoloError | User | No |
| SOLO-4092 | MirrorNodeBlockNodeSourceUnavailableSoloError | User | No |
| SOLO-4093 | InvalidAdminPublicKeySoloError | User | No |
| SOLO-4094 | ConfigValueTypeMismatchSoloError | User | No |
| SOLO-4095 | ChainIdMismatchSoloError | User | No |
| SOLO-4096 | NoConsensusNodesForNodeAddSoloError | User | No |
| SOLO-4097 | MirrorNodeBucketSourceUnavailableSoloError | User | No |
| SOLO-5090 | PodLogsCrdInvalidSoloError | Infrastructure | Yes |
System
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-2032 | MinioOperatorCrdsOrphanedSoloError | User | No |
| SOLO-5001 | ResourceNotFoundError | Infrastructure | No |
| SOLO-5002 | ClusterConnectionFailedError | Infrastructure | Yes |
| SOLO-5003 | PortForwardRefreshFailedError | Infrastructure | Yes |
| SOLO-5004 | PortForwardStatusFailedError | Infrastructure | Yes |
| SOLO-5005 | NamespaceNotFoundSoloError | User | No |
| SOLO-5006 | PodNotFoundSoloError | Infrastructure | Yes |
| SOLO-5007 | HaproxyPodsNotFoundSoloError | Infrastructure | Yes |
| SOLO-5008 | LoadBalancerNotFoundSoloError | Infrastructure | Yes |
| SOLO-5009 | KubeContextNotFoundSoloError | Solo | No |
| SOLO-5010 | ConsensusNodeNotInConfigSoloError | Solo | No |
| SOLO-5011 | K8sSecretCreateFailedSoloError | Infrastructure | Yes |
| SOLO-5012 | StatesDirectoryNotFoundSoloError | User | No |
| SOLO-5013 | PortForwardMissingSoloError | Infrastructure | Yes |
| SOLO-5014 | NoPvcFoundSoloError | User | No |
| SOLO-5015 | ClusterReferenceUndeterminedSoloError | Solo | No |
| SOLO-5016 | UpgradeVersionFetchFailedSoloError | Infrastructure | Yes |
| SOLO-5017 | MultipleDeploymentsFoundSoloError | User | No |
| SOLO-5018 | GrpcProxyEndpointFailedSoloError | Infrastructure | Yes |
| SOLO-5019 | ExplorerPodNotFoundSoloError | Infrastructure | No |
| SOLO-5020 | ExplorerNotInRemoteConfigSoloError | User | No |
| SOLO-5021 | RelayPodNotFoundSoloError | Infrastructure | No |
| SOLO-5022 | RelayNotInRemoteConfigSoloError | User | No |
| SOLO-5023 | MirrorNodePodsNotFoundSoloError | Infrastructure | No |
| SOLO-5024 | MirrorIngressControllerPodNotFoundSoloError | Infrastructure | No |
| SOLO-5025 | MirrorNodeNotInRemoteConfigSoloError | User | No |
| SOLO-5026 | ClusterNotFoundInRemoteConfigSoloError | User | No |
| SOLO-5027 | GitHubApiRequestFailedError | Infrastructure | Yes |
| SOLO-5028 | GitHubApiHttpResponseError | Infrastructure | Yes |
| SOLO-5029 | GitHubApiResponseParseFailedError | Infrastructure | No |
| SOLO-5030 | GitHubApiResponseMissingTagNameError | Infrastructure | No |
| SOLO-5031 | BlockNodePodNotFoundSoloError | Infrastructure | Yes |
| SOLO-5032 | BlockNodeNotReadySoloError | Infrastructure | Yes |
| SOLO-5033 | BlockNodeNotInRemoteConfigSoloError | User | No |
| SOLO-5034 | ExternalBlockNodeNotInRemoteConfigSoloError | User | No |
| SOLO-5035 | HelmRepoSetupFailedSoloError | Infrastructure | No |
| SOLO-5036 | HelmRepoCheckFailedSoloError | Infrastructure | No |
| SOLO-5037 | HelmChartListFailedSoloError | Infrastructure | No |
| SOLO-5038 | HelmChartGenericInstallFailedSoloError | Infrastructure | No |
| SOLO-5039 | HelmChartUninstallFailedSoloError | Infrastructure | No |
| SOLO-5040 | HelmChartUpgradeFailedSoloError | Infrastructure | No |
| SOLO-5041 | FileNotFoundSoloError | User | No |
| SOLO-5042 | FileCopyFailedSoloError | Infrastructure | No |
| SOLO-5043 | FileEmptySoloError | User | No |
| SOLO-5044 | FileInvalidJsonSoloError | User | No |
| SOLO-5045 | DirectoryCreationFailedSoloError | Infrastructure | No |
| SOLO-5046 | ArchiveUnzipFailedSoloError | Infrastructure | No |
| SOLO-5047 | ArchiveTarFailedSoloError | Infrastructure | No |
| SOLO-5048 | ArchiveUntarFailedSoloError | Infrastructure | No |
| SOLO-5049 | DependencyVersionCheckFailedSoloError | Infrastructure | No |
| SOLO-5050 | DependencyNotFoundSoloError | Infrastructure | No |
| SOLO-5051 | DependencyManagerNotFoundSoloError | Solo | No |
| SOLO-5052 | DependencyInstallFailedSoloError | Infrastructure | No |
| SOLO-5053 | DependencyInstallDirectoryConflictSoloError | User | No |
| SOLO-5054 | GitHubReleasesNotFoundSoloError | Infrastructure | Yes |
| SOLO-5055 | GitHubReleaseTagNotFoundSoloError | Infrastructure | No |
| SOLO-5056 | GitHubReleaseAssetNotFoundSoloError | Infrastructure | No |
| SOLO-5057 | HomebrewInstallFailedSoloError | Infrastructure | No |
| SOLO-5058 | PodmanMachineInspectFailedSoloError | Infrastructure | No |
| SOLO-5059 | DockerAuthStaleSoloError | User | No |
| SOLO-5060 | PvcCreationFailedSoloError | Infrastructure | No |
| SOLO-5061 | KubernetesApiInvalidResponseSoloError | Infrastructure | No |
| SOLO-5062 | IngressClassListFailedSoloError | Infrastructure | No |
| SOLO-5063 | MultipleItemsFoundSoloError | Solo | No |
| SOLO-5064 | PodCreationFailedSoloError | Infrastructure | No |
| SOLO-5065 | PackageDownloadFailedSoloError | Infrastructure | Yes |
| SOLO-5066 | ChecksumReadFailedSoloError | Infrastructure | No |
| SOLO-5067 | ContainerInvalidPathSoloError | Solo | No |
| SOLO-5068 | ContainerOperationFailedSoloError | Infrastructure | No |
| SOLO-5069 | PostgresPodNotFoundSoloError | Infrastructure | No |
| SOLO-5070 | InitSystemFilesFailedSoloError | Infrastructure | No |
| SOLO-5071 | CacheProviderNotConfiguredSoloError | Solo | No |
| SOLO-5072 | PodTerminationTimeoutSoloError | Infrastructure | Yes |
| SOLO-5073 | ClusterRoleCheckFailedSoloError | Infrastructure | No |
| SOLO-5074 | UnsupportedLinuxDistributionSoloError | Infrastructure | No |
| SOLO-5075 | BlockNodesJsonEmptySoloError | User | No |
| SOLO-5076 | HelmChartPullNoArchiveSoloError | Infrastructure | No |
| SOLO-5077 | PodmanRuntimeConfigurationFailedSoloError | Infrastructure | No |
| SOLO-5078 | ClusterUnreachableError | Infrastructure | Yes |
| SOLO-5079 | KindClusterStoppedError | Infrastructure | Yes |
| SOLO-5080 | ContainerEngineNotRunningError | User | Yes |
| SOLO-5081 | PodNotReadySoloError | Infrastructure | Yes |
| SOLO-5082 | PortForwardStopFailedError | Infrastructure | Yes |
| SOLO-5083 | SoloLogsDirectoryNotWritableSoloError | Infrastructure | No |
| SOLO-5084 | PvcMountVerificationFailedSoloError | Infrastructure | No |
| SOLO-5085 | SavedStateHashToolMissingSoloError | Infrastructure | No |
| SOLO-5086 | CacheManifestDownloadFailedSoloError | Infrastructure | Yes |
| SOLO-5087 | CacheManifestInvalidSoloError | Solo | No |
| SOLO-5088 | CacheArchiveHashMismatchSoloError | Infrastructure | No |
| SOLO-5089 | CachedFileInaccessibleSoloError | User | No |
| SOLO-5091 | BlockNodeBlocksUnavailableSoloError | Infrastructure | Yes |
| SOLO-5092 | CacheManifestUnpublishedSoloError | Infrastructure | No |
| SOLO-5093 | ContainerEngineNotFoundSoloError | User | No |
| SOLO-5094 | ContainerEngineStartFailedSoloError | Infrastructure | Yes |
| SOLO-5095 | KindClusterContainerNotFoundSoloError | User | No |
| SOLO-9001 | TimeoutSoloError | Infrastructure | Yes |
Internal
| Code | Class | Ownership | Retryable |
|---|---|---|---|
| SOLO-9002 | UnsupportedOperationError | Solo | No |
| SOLO-9003 | ReadRemoteConfigBeforeLoadError | Solo | No |
| SOLO-9004 | WriteRemoteConfigBeforeLoadError | Solo | No |
| SOLO-9005 | DataValidationError | Solo | No |
| SOLO-9006 | LoggerMessageGroupNotFoundError | Solo | No |
| SOLO-9007 | CommandReturnedFalseError | Solo | No |
| SOLO-9008 | RemoteConfigUnsupportedComponentError | User | No |
| SOLO-9010 | RemoteConfigContextUnavailableError | Solo | No |
| SOLO-9011 | CacheImageTemplateUndeclaredError | Solo | No |
| SOLO-9012 | InjectedFailureSoloError | Solo | No |
| SOLO-9013 | PipelineCancelledSoloError | Solo | No |
| SOLO-9014 | UncaughtFatalErrorSoloError | Solo | No |
4.1.1 - Configuration
4.1.1.1 - SOLO-1001
| Code | SOLO-1001 |
| Category | Configuration |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo reads its local configuration but no file exists at the resolved path (~/.solo/local-config.yaml, or $SOLO_HOME/local-config.yaml when SOLO_HOME is set). The local config records cluster references, deployments, and the active user context, so most commands load it before doing any work. solo creates the file the first time a command loads it, so a missing file means SOLO_HOME points at a different directory than the one the file was created in, or that it was manually moved or deleted.
Troubleshooting Steps
- Create a local config: solo deployment config create –deployment
–namespace
4.1.1.2 - SOLO-1002
| Code | SOLO-1002 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot persist the local configuration to disk at ~/.solo/local-config.yaml (or $SOLO_HOME/local-config.yaml). The local config is rewritten whenever solo records a new cluster reference, deployment, or context, and this error wraps the underlying filesystem failure (cause). It means the data was prepared but could not be written: typical causes are missing write permissions on the ~/.solo directory, a read-only or full disk, or a parent directory that is missing or locked.
Troubleshooting Steps
- Check file system permissions for ~/.solo
4.1.1.3 - SOLO-1003
| Code | SOLO-1003 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo fails to reload the local configuration from its on-disk source — that is, the re-read and re-parse of ~/.solo/local-config.yaml (or $SOLO_HOME/local-config.yaml) did not complete; the message names the offending file and the underlying failure is wrapped in cause. Unlike LocalConfigNotFoundSoloError, the file is present: it could not be read (insufficient permissions, an I/O error) or its contents could not be parsed into the expected configuration because the file is malformed or corrupt. A malformed file can be regenerated from a cluster’s remote config with solo deployment config import.
Troubleshooting Steps
- Check file system permissions and contents of the file:
4.1.1.4 - SOLO-1004
| Code | SOLO-1004 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a deployment spans multiple clusters and solo finds that the remote configuration stored in two of them does not agree; the message names the two clusters whose copies diverged. solo keeps the remote config as a ConfigMap that must be an identical replica in every cluster of the deployment, so it compares them and raises this when they differ. The usual cause is a prior write that was applied to one cluster but not the others (a partial or failed update), a ConfigMap that was edited manually, or clusters that have otherwise drifted out of sync.
Troubleshooting Steps
- Inspect both configs: kubectl get configmap -n
- Sync manually before retrying
4.1.1.5 - SOLO-1005
| Code | SOLO-1005 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the local configuration file (~/.solo/local-config.yaml, or $SOLO_HOME/local-config.yaml) parses as valid YAML but is missing required top-level keys such as deployments or clusterRefs; the message names the file and the missing keys. Without this check a partial file — typically left behind by an interrupted write or a manual edit — would silently load as a valid-but-empty config and only surface later as a confusing DeploymentNotFoundError. The file can be regenerated from a cluster’s remote config with solo deployment config import.
Troubleshooting Steps
- Or restore the missing keys in the file manually:
4.1.1.6 - SOLO-1006
| Code | SOLO-1006 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the remote configuration stored in the solo-remote-config ConfigMap cannot be turned into a configuration object: the remote-config-data value is empty, is not parseable as YAML, or parses to something that is not a configuration object (a bare scalar, null, or a sequence). solo treats that ConfigMap as the source of truth for a deployment and reads it before almost any other work, so an unusable value blocks the whole command. The value is normally only written by solo itself, so this means it was hand-edited, truncated by a partial or interrupted write, or otherwise corrupted in the cluster. The offending value is captured on the error (meta.capturedData) so it can be inspected after the fact.
Troubleshooting Steps
- Inspect the stored value: kubectl get configmap solo-remote-config -n
-o yaml - The full captured value is recorded in ~/.solo/logs/solo.log
- Recover by deleting and recreating the cluster: solo one-shot single destroy, then solo one-shot single deploy
- Collect a diagnostics bundle: solo deployment diagnostics debug
- If this is reproducible or looks like a solo bug, open an issue or PR with the diagnostics bundle: https://github.com/hiero-ledger/solo/issues
4.1.1.7 - SOLO-1007
| Code | SOLO-1007 |
| Category | Configuration |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot migrate the legacy local configuration from the old cache path ($SOLO_HOME/cache/local-config.yaml) to the current path ($SOLO_HOME/local-config.yaml). The migration copies the legacy file to the current path and validates it before the legacy file is removed, so this error is raised either because a filesystem operation failed (copy/remove/mkdir, wrapped in cause) or because the legacy configuration is corrupt and cannot be parsed. In both cases the legacy file is left in place — it is never deleted while unvalidated — and the corrupt copy (if any) is discarded, so no configuration is silently propagated or lost.
Troubleshooting Steps
- Inspect the legacy file at
. If it is corrupt, fix the YAML or remove it, then re-run the command. Also verify file system permissions for your Solo home directory.Inspect the legacy local configuration file. If it is corrupt, fix the YAML or remove it, then re-run the command. Also verify file system permissions for your Solo home directory.
4.1.1.8 - SOLO-1008
| Code | SOLO-1008 |
| Category | Configuration |
| Ownership | User |
| Retryable | No |
Description
Thrown when the solo-remote-config ConfigMap that backs a deployment cannot be found and the deployment targets a local kind cluster. solo keeps the authoritative deployment state in that ConfigMap, so its absence means the deployment recorded in the local config no longer has anything backing it in the cluster; the usual causes are a kind cluster that was deleted and recreated, a namespace that was removed with kubectl, or a ConfigMap that was deleted by hand. A local kind cluster holds nothing worth preserving, so the recorded deployment cannot be resumed and the fix is to tear the leftover state down with solo one-shot single destroy and deploy again from a clean slate. solo one-shot single deploy detects this state up front and offers that teardown itself; every other command reports this error and stops. Deployments on non-kind clusters fail with the generic resource-not-found error instead, since their state may still be recoverable.
Troubleshooting Steps
- Confirm the kind cluster and namespace still exist: kind get clusters && kubectl get namespaces
- Inspect the remote config ConfigMap: kubectl get configmap solo-remote-config -n
- Tear the leftover state down before deploying again: solo one-shot single destroy –deployment
4.1.1.9 - SOLO-1009
| Code | SOLO-1009 |
| Category | Configuration |
| Ownership | User |
| Retryable | No |
Description
Thrown by network deploy when the solo-remote-config ConfigMap that backs a deployment cannot be found. network destroy leaves the namespace and the recorded deployment in place unless it is asked to remove PVCs and secrets as well, so the deployment itself is not gone — only the ConfigMap tracking it. deployment cluster attach only (re)creates that ConfigMap when the deployment has no clusters recorded yet; once a cluster-ref is already attached it instead expects the ConfigMap to exist and fails the same way. The only way back to a working state is therefore to delete and recreate the deployment’s local config so the cluster-ref attach is treated as new, which recreates the ConfigMap fresh. The consensus keys have to be regenerated alongside it, since a successful network deploy removes the cached copies from disk once they are uploaded to cluster secrets.
Troubleshooting Steps
- Inspect the remote config ConfigMap: kubectl get configmap solo-remote-config -n
- The deployment record still exists locally, but the remote config backing it is gone and cannot be recreated in place. Recreate the local deployment config so cluster attach treats it as new, then reattach the cluster and regenerate the consensus keys:
- solo deployment config delete –deployment
- solo deployment config create -d
-n -q - solo deployment cluster attach -d
-c -q –num-consensus-nodes - solo keys consensus generate -d
-q –gossip-keys –tls-keys - Set –num-consensus-nodes to the node count this deployment had before, then re-run network deploy
4.1.2 - Deployment
4.1.2.1 - SOLO-2001
| Code | SOLO-2001 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo deployment config create cannot record a new deployment; the underlying failure is wrapped in cause. Creating a deployment writes its entry to the local configuration and provisions the associated namespace, so this is raised when that work fails — for example the local config could not be written, or the Kubernetes API rejected or could not create the namespace. It is retryable because a transient cluster or filesystem issue often clears on a second attempt.
Troubleshooting Steps
- Check the logs for details: tail -n 100 ~/.solo/logs/solo.log
4.1.2.2 - SOLO-2002
| Code | SOLO-2002 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo deployment config create is asked to create a deployment whose name is already present in the local configuration; the message names the conflicting deployment. Deployment names must be unique because solo keys each deployment’s namespace and cluster references by name, so it refuses to overwrite an existing entry. Choose a different name, or operate on the existing deployment instead of recreating it.
Troubleshooting Steps
- Check existing deployments: solo deployment config list
- Choose a different name for your deployment
4.1.2.3 - SOLO-2003
| Code | SOLO-2003 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a command resolves a deployment by name but that name is not registered in the local configuration; the error message names the deployment that was requested. solo looks the deployment up to find its namespace and cluster references before acting, so the lookup fails when the --deployment value is misspelled, when the deployment was never created with solo deployment config create, or when it was removed by a prior delete. It can also surface after switching SOLO_HOME to a config that does not contain the deployment.
Troubleshooting Steps
- List available deployments: solo deployment config list
- Create a deployment if needed: solo deployment config create
4.1.2.4 - SOLO-2004
| Code | SOLO-2004 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a deployment is deleted while it still has live components running in one of its clusters; the message names the deployment and the clusterReference where resources remain. Before removing a deployment’s local entry, solo checks each attached cluster and refuses to proceed if it still hosts components (mirror node, relay, explorer, block node, or the consensus network), since deleting the entry would orphan those running workloads. Destroy the components first, then delete the deployment.
Troubleshooting Steps
- Destroy all components in the deployment before deleting it:
- solo mirror node destroy
- solo relay node destroy
- solo explorer node destroy
- solo block node destroy
- solo consensus network destroy
4.1.2.5 - SOLO-2005
| Code | SOLO-2005 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when removing a deployment fails; the underlying failure is wrapped in cause. Deleting a deployment removes its entry from the local configuration and may reach into each attached cluster to clean up, so this is raised when that work cannot complete — most often because one of the deployment’s cluster references or its kubeconfig context is invalid or unreachable. It is retryable, since a transient connectivity problem often clears on a later attempt once the contexts are reachable again.
Troubleshooting Steps
- Check logs for details: tail -n 100 ~/.solo/logs/solo.log
- Verify cluster references and their contexts are valid: solo cluster-ref config list
4.1.2.6 - SOLO-2006
| Code | SOLO-2006 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when attaching a cluster to a deployment fails due to an unexpected error; the underlying failure is wrapped in cause. Specific failures such as missing cluster references or missing deployments are raised as dedicated error types, so this error serves as the fallback for unexpected errors encountered while attaching a cluster. It is not retryable, as unexpected runtime or code errors will generally produce the same failure on retry.
Troubleshooting Steps
- Check logs for details: tail -n 100 ~/.solo/logs/solo.log
4.1.2.7 - SOLO-2007
| Code | SOLO-2007 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo deployment config list cannot enumerate the configured deployments; the underlying failure is wrapped in cause. Listing reads the deployment entries from the local configuration and may consult the clusters they reference, so this is raised when that read fails — for example the local config could not be read or parsed, or a referenced cluster could not be queried. It is retryable because transient filesystem or cluster issues often resolve on a later attempt.
Troubleshooting Steps
- Check logs for details: tail -n 100 ~/.solo/logs/solo.log
4.1.2.8 - SOLO-2008
| Code | SOLO-2008 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a command refers to a cluster reference that is not registered in the local configuration; the message names the missing reference. A cluster reference is the named link between solo and a kubeconfig context, created with solo cluster-ref config connect, so this is raised when the supplied name was never connected, was misspelled, or was disconnected. Connect the cluster reference (or correct the name) before retrying.
Troubleshooting Steps
- List available cluster references: solo cluster-ref config list
- Connect a cluster: solo cluster-ref config connect
4.1.2.9 - SOLO-2009
| Code | SOLO-2009 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a cluster reference that is already attached to the deployment is added again; the message names the duplicate reference. solo keeps each cluster reference attached to a deployment at most once, so it rejects a second add rather than creating a conflicting duplicate entry. If you intend to re-add it (for example to change its binding), disconnect it first and then connect it again.
Troubleshooting Steps
- List current cluster references: solo cluster-ref config list
- Disconnect it first if you want to re-add it: solo cluster-ref config disconnect
4.1.2.10 - SOLO-2010
| Code | SOLO-2010 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a command needs a target Kubernetes namespace but none could be resolved. solo determines the namespace from the --namespace flag or from the selected deployment’s configuration, so this is raised when neither is available — the flag was not passed and the deployment has no namespace recorded. Supply --namespace, or select a deployment whose configuration defines one.
Troubleshooting Steps
- Ensure a namespace is specified: pass –namespace
to your command - Check deployment config: solo deployment config info –deployment
4.1.2.11 - SOLO-2011
| Code | SOLO-2011 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when an operation targets a deployment that has no clusters attached; the message names the deployment. A deployment must have at least one cluster reference attached before solo can place or manage its components, so this is raised when the deployment exists but its cluster list is empty — typically because solo deployment cluster attach has not yet been run for it. Attach a cluster to the deployment before retrying.
Troubleshooting Steps
- Attach a cluster to the deployment: solo deployment cluster attach –deployment
4.1.2.12 - SOLO-2012
| Code | SOLO-2012 |
| Category | Deployment |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo cannot resolve which cluster reference a deployment should use; the message names the deployment. Internally a command expected the deployment to yield a single, unambiguous cluster reference (so it knows where to act) but the resolution returned nothing usable. While an unattached deployment is the visible trigger, this is classified as a Solo-owned error because the calling code should have ensured a cluster was attached before reaching this point — it points to a missing precondition in solo’s flow.
Troubleshooting Steps
- Verify the deployment has clusters attached: solo deployment config info
- Attach the cluster reference to the deployment: solo deployment cluster attach
4.1.2.13 - SOLO-2013
| Code | SOLO-2013 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a cluster reference exists in the local configuration but has no kubeconfig context bound to it; the message names the cluster reference. solo needs the context to know which cluster the reference points at, so this is raised when the mapping is missing — usually because the reference was recorded without being connected to a context, or the binding was removed. Connect a kubeconfig context to the cluster reference before retrying.
Troubleshooting Steps
- Connect a kubeconfig context to the cluster: solo cluster-ref config connect
4.1.2.14 - SOLO-2014
| Code | SOLO-2014 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when a command needs at least one deployment to act on but the local configuration contains none. solo stores every deployment in local config and several commands assume one already exists, so this is raised when that list is empty — typically because no deployment has been created yet, or because they were all deleted (or the active SOLO_HOME/local config does not contain any). Create a deployment before running the command.
Troubleshooting Steps
- Create a deployment: solo deployment config create
4.1.2.15 - SOLO-2015
| Code | SOLO-2015 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot enumerate the forwarded ports for a deployment; the underlying failure is wrapped in cause. Listing ports queries the Kubernetes API in the deployment’s namespace to discover the active port-forwards exposing its components, so this is raised when that query fails — typically because the cluster’s API server is unreachable or the namespace cannot be inspected. It is retryable, as a transient connectivity problem often clears on a later attempt.
Troubleshooting Steps
- Check logs for details: tail -n 100 ~/.solo/logs/solo.log
- Verify the Kubernetes API server is reachable: kubectl cluster-info
- List port-forwards in the namespace to check for any issues: kubectl get port-forwards -n
4.1.2.16 - SOLO-2016
| Code | SOLO-2016 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cluster-ref config setup cannot install the cluster-level shared infrastructure that deployments depend on — the solo-cluster-setup chart and its components (Prometheus, MinIO, metrics-server, and the cluster role). It wraps the underlying failure (cause.message), which is most often a failed Helm release (bad chart version or values), an image that cannot be pulled, missing RBAC permissions on the target cluster, or a cluster that lacks the CPU/memory to schedule the new pods.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List installed Helm releases: helm list -A
- Inspect cluster pods: kubectl get pods -A
- Re-run cluster setup: solo cluster-ref config setup
4.1.2.17 - SOLO-2017
| Code | SOLO-2017 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cluster-ref config reset cannot tear down the cluster-level resources that setup installed (the solo-cluster-setup chart and its components); the underlying failure is wrapped in cause. It means the uninstall did not complete cleanly — for example a Helm release could not be removed, or the cluster API was unreachable mid-reset — so some resources may still be present. Inspect the remaining Helm releases and pods to see what was left behind.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster state: kubectl get pods -A
- Check Helm releases still present: helm list -A
- Re-run cluster reset: solo cluster-ref config reset
4.1.2.18 - SOLO-2018
| Code | SOLO-2018 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the MinIO Operator Helm chart fails to install; the underlying failure is wrapped in cause. MinIO provides the S3-compatible object storage that solo’s cluster-level stack relies on, so its install is part of solo cluster-ref config setup. The failure is usually a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster lacking the resources/connectivity to schedule the operator.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster state: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.2.19 - SOLO-2019
| Code | SOLO-2019 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the Prometheus stack Helm chart fails to install; the underlying failure is wrapped in cause. The Prometheus stack supplies the monitoring and metrics collection for the cluster-level stack installed by solo cluster-ref config setup. The failure is typically a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster without the resources/connectivity to schedule its pods.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster pods: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.2.20 - SOLO-2020
| Code | SOLO-2020 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the metrics-server Helm chart fails to install; the underlying failure is wrapped in cause. metrics-server provides the resource-usage metrics API the cluster-level stack depends on, installed as part of solo cluster-ref config setup. The failure is usually a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster lacking the resources/connectivity to schedule the pod.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster pods: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.2.21 - SOLO-2021
| Code | SOLO-2021 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the pod-monitor-role ClusterRole cannot be installed; the underlying failure is wrapped in cause. This ClusterRole grants the monitoring stack permission to scrape pods cluster-wide, so it is created as part of solo cluster-ref config setup. The failure most often means the current kubeconfig user lacks the RBAC permission to create ClusterRoles, but it can also stem from an API server that is unreachable or rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify RBAC permissions: kubectl get clusterroles
- Inspect cluster state: kubectl get pods -A
4.1.2.22 - SOLO-2022
| Code | SOLO-2022 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a cluster’s Kubernetes API server does not become ready within the allowed number of attempts; the message names the context and the maxAttempts tried, and wraps the last failure in cause. solo polls the API server before proceeding so it does not act against a cluster that is still starting, and raises this once polling is exhausted. It is retryable because a cluster that is merely slow to come up (for example a Kind cluster still initialising) often becomes ready shortly after; a persistent failure points to a cluster that is down, unreachable, or pointed at by the wrong context.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the cluster context is reachable: kubectl cluster-info –context
- Check cluster node status: kubectl get nodes
- Inspect cluster pods: kubectl get pods -A
4.1.2.23 - SOLO-2023
| Code | SOLO-2023 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot configure networking for a Kind cluster — either the Kind network setup itself or the MetalLB Helm repository configuration it depends on; the underlying failure is wrapped in cause. solo configures MetalLB so that LoadBalancer services in the local Kind cluster receive reachable addresses, and raises this when that setup fails. Common roots are Docker not running (Kind needs it), an unreachable or misconfigured Helm repository, or a problem with the Kind cluster’s Docker network.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Docker is running: docker ps
- Check existing Kind clusters: kind get clusters
- Verify Helm repository access: helm repo list
4.1.2.24 - SOLO-2024
| Code | SOLO-2024 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during solo config ops backup when a particular resource cannot be exported into the backup; the message names the resourceType and wraps the underlying failure in cause. Backup reads each resource from the cluster and writes it to the backup archive, so this is raised when reading a resource or writing it out fails — for example the Kubernetes API is unreachable, the deployment or resource no longer exists, or the archive destination cannot be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl get pods -A
- Check that the deployment exists: solo deployment config list
- Run backup again: solo config ops backup
4.1.2.25 - SOLO-2025
| Code | SOLO-2025 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during solo config ops restore-config when a particular resource cannot be imported from a backup; the message names the resourceType and wraps the underlying failure in cause. Restore reads each resource from the backup archive and applies it to the cluster, so this is raised when reading the archive entry or applying it fails — for example the backup archive is incomplete or corrupt, the resource is invalid, or the Kubernetes API is unreachable or rejected it.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl get pods -A
- Verify the backup archive is complete and valid
- Run restore: solo config ops restore-config
4.1.2.26 - SOLO-2026
| Code | SOLO-2026 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo config ops restore-clusters cannot recreate the clusters captured in a backup; the underlying failure is wrapped in cause. This step reads the backup archive and rebuilds the cluster(s) it describes (for example recreating a Kind cluster) before the rest of a restore can proceed, so the error means that rebuild failed. Common roots are an invalid or incomplete backup archive, an incorrect input directory, or Docker/Kind not being available to create the clusters.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the backup archive is valid and the input directory is correct
- Check Docker or Kind cluster availability: kind get clusters
- Run cluster restore: solo config ops restore-clusters
4.1.2.27 - SOLO-2027
| Code | SOLO-2027 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo consensus network deploy cannot bring up the consensus network; the underlying failure is wrapped in cause. This step installs the solo-deployment Helm chart that creates the consensus node pods and their supporting services, so the error means that install did not succeed. Typical roots are a Helm release failure (bad chart version or values), an image that cannot be pulled, insufficient cluster resources to schedule the nodes, or a loss of connectivity to the cluster during the deploy.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect consensus node pods: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.2.28 - SOLO-2029
| Code | SOLO-2029 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo needs to act on a block node but cannot determine which cluster (kubeconfig context) it lives in; the message names the blockNodeId. solo maps each block node to a registered cluster reference to find the context for its operations, so this is raised when no such mapping resolves — typically because the block node is not associated with a registered cluster reference, or the referenced cluster is missing from the deployment configuration.
Troubleshooting Steps
- List registered cluster references: solo cluster-ref config list
- Verify the block node is associated with a registered cluster
- Check deployment configuration: solo deployment config info
4.1.2.29 - SOLO-2030
| Code | SOLO-2030 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo needs to act on a mirror node but cannot determine which cluster (kubeconfig context) it lives in; the message names the mirrorNodeId. solo maps each mirror node to a registered cluster reference to find the context for its operations, so this is raised when no such mapping resolves — typically because the mirror node is not associated with a registered cluster reference, or the referenced cluster is missing from the deployment configuration.
Troubleshooting Steps
- List registered cluster references: solo cluster-ref config list
- Verify the mirror node is associated with a registered cluster
- Check deployment configuration: solo deployment config info
4.1.2.30 - SOLO-2031
| Code | SOLO-2031 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo deployment config import cannot reconstruct the local config from a cluster’s solo-remote-config ConfigMap: the cluster is unreachable, no Solo deployment exists in the targeted context/namespace, the remote config is unparseable, or the selection is ambiguous in quiet mode. Retryable because transient connectivity issues often resolve on retry.
Troubleshooting Steps
- Verify the kube context is reachable: kubectl –context
get namespaces - Verify the targeted namespace contains a Solo deployment (solo-remote-config ConfigMap)
- Check logs for details: tail -n 100 ~/.solo/logs/solo.log
4.1.2.31 - SOLO-2033
| Code | SOLO-2033 |
| Category | Deployment |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo consensus network deploy is used for a network that already has the Solo deployment chart installed. Deploy is a first-time operation and does not perform the freeze, reconfiguration, and restart lifecycle required by an existing consensus network.
Troubleshooting Steps
- Upgrade the existing network: solo consensus network upgrade –deployment
- For a fresh deployment, destroy the existing network before running network deploy
4.1.2.32 - SOLO-2034
| Code | SOLO-2034 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the Grafana Alloy Helm chart fails to install; the underlying failure is wrapped in cause. Grafana Alloy collects the pod logs selected by PodLogs custom resources and ships them to the Loki log store, both installed by solo cluster-ref config setup --grafana-alloy. The failure is typically a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster without the resources/connectivity to schedule its pods.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster pods: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.2.33 - SOLO-2035
| Code | SOLO-2035 |
| Category | Deployment |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown during cluster setup when the Loki Helm chart fails to install; the underlying failure is wrapped in cause. Loki stores the pod logs collected by Grafana Alloy, both installed by solo cluster-ref config setup --grafana-alloy. The failure is typically a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster without the resources/connectivity to schedule its pods.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect cluster pods: kubectl get pods -A
- Check Helm release status: helm list -A
- Verify cluster connectivity: kubectl cluster-info
4.1.3 - Component
4.1.3.1 - SOLO-3001
| Code | SOLO-3001 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a Hedera SDK transaction that solo submitted to a consensus node receives a receipt whose status is not SUCCESS. The error message carries the operation that failed and the raw network status code (for example node create transaction failed with status: INVALID_SIGNATURE). This means the network reached and rejected the transaction rather than failing to deliver it: common causes are a node that has not yet reached ACTIVE during setup, staking, or a network upgrade; an operator/admin key that does not match the account; or an address-book/state precondition that the transaction violated. The specific status code identifies which.
Troubleshooting Steps
- Check the solo logs for details: tail -n 100 ~/.solo/logs/solo.log
- Verify the node pod is running: kubectl get pods -n
-l solo.hedera.com/type=network-node - Consult the Hedera documentation for the meaning of the status code
4.1.3.2 - SOLO-3003
| Code | SOLO-3003 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot upload the build.zip artifact; the underlying failure is wrapped in cause. solo uploads the packaged build so nodes can be provisioned from it, so this means the upload failed — for example the source file was missing or unreadable, or the destination was unreachable. It is retryable.
Troubleshooting Steps
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check node pod status: kubectl get pods -n
-l solo.hedera.com/type=network-node - Inspect the pod for more detail: kubectl describe pod
-n
4.1.3.3 - SOLO-3004
| Code | SOLO-3004 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot copy a local build into a consensus node; the underlying failure is wrapped in cause. When running with a local platform build, solo copies the build artifacts into the node pod, so this means that copy failed — for example the pod was not reachable, the destination path was not writable, or the connection dropped mid-copy. It is retryable.
Troubleshooting Steps
- Check pod status: kubectl get pods -n
-l solo.hedera.com/type=network-node - Verify the local build path is valid and readable
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.4 - SOLO-3005
| Code | SOLO-3005 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a Java Flight Recorder (JFR) operation on a consensus node pod fails; the message names the operation and the pod. solo runs JFR commands inside the node container to capture profiling data, so this means that command failed — for example the pod was not reachable or the command returned an error. It is retryable.
Troubleshooting Steps
- Check if the node pod is running: kubectl get pod
-n - Verify the pod has jcmd available: kubectl exec
-n – which jcmd - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.5 - SOLO-3006
| Code | SOLO-3006 |
| Category | Component |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo cannot find the ServicesMain process id inside a consensus node pod; the message names the pod. JFR profiling must attach to the running node process, so this is raised when that process cannot be located — which points to an unexpected container state or a defect in how solo locates the process, and is treated as an internal Solo error.
Troubleshooting Steps
- Verify the consensus node is running inside the pod: kubectl exec
– ps axww -o pid,command - Check node startup logs: kubectl logs
-n - Restart the node if ServicesMain is absent: solo consensus node restart
4.1.3.6 - SOLO-3007
| Code | SOLO-3007 |
| Category | Component |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo cannot create the debug archive it assembles for troubleshooting; the underlying failure is wrapped in cause. The archive bundles a node’s logs and diagnostic data, and reaching this failure points to a problem in solo’s archive-creation logic rather than user or infrastructure input, so it is treated as an internal Solo error and should be reported with the full error output.
Troubleshooting Steps
- Verify the output directory is writable
- Check available disk space: df -h
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.7 - SOLO-3008
| Code | SOLO-3008 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo fails while building the block-nodes configuration; the underlying failure is wrapped in cause. solo generates the configuration that tells consensus nodes how to reach the block nodes, so this means that generation step failed — for example required connection details could not be resolved. It is retryable, since a transient resolution problem often clears on a later attempt.
Troubleshooting Steps
- Check block node pod status: kubectl get pods -n
-l block-node.hiero.com/type=block-node - Check network node pod status: kubectl get pods -n
-l solo.hedera.com/type=network-node - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the cluster is reachable: kubectl cluster-info –context
4.1.3.8 - SOLO-3009
| Code | SOLO-3009 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot install a Helm chart; the message names the chart and wraps the underlying failure in cause. solo installs charts to deploy its components, so this means the Helm install failed — for example a bad chart version or values, an image that cannot be pulled, or a cluster that is unreachable or short on resources. It is retryable, since transient registry or cluster issues often clear on a later attempt.
Troubleshooting Steps
- Check Helm release status: helm list -n
- Review Helm errors: helm status
-n - Verify the cluster is reachable: kubectl cluster-info –context
- Retry after inspecting solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.9 - SOLO-3010
| Code | SOLO-3010 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo consensus network destroy cannot tear down the consensus network; the underlying failure is wrapped in cause. Destroy uninstalls the network Helm release and removes its consensus node pods and resources, so this means teardown did not complete — for example a Helm release could not be removed or the cluster API was unreachable.
Troubleshooting Steps
- Check remaining Helm releases: helm list -A
- Check for stuck namespaces: kubectl get namespaces
- Manually clean up: helm uninstall
-n - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.10 - SOLO-3011
| Code | SOLO-3011 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a consensus node does not reach the expected status within the allotted polling attempts; the message names the node alias, the expected status, and the attempt count (attempt/maxAttempts). solo polls node status while waiting for nodes to come up or change state, and raises this once the attempts are exhausted without the node reaching the expected status — for example the node is crash-looping, stuck during startup, or unable to join the network.
Troubleshooting Steps
- Check node pod status: kubectl get pods -n
-l solo.hedera.com/node-name= - View node logs: kubectl logs -n
-l solo.hedera.com/node-name= - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.11 - SOLO-3012
| Code | SOLO-3012 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a rapid-fire load test step fails to execute; the message describes the failing step and, when present, wraps the underlying cause. Rapid-fire runs load against the network, so this means one of its execution steps did not succeed. It is retryable, since transient cluster or network issues during the test often clear on a later attempt.
Troubleshooting Steps
- Check NLG pod logs for TPS output and errors: kubectl logs -n
-l app.kubernetes.io/instance=network-load-generator - Retry with lower load parameters or a reduced –max-tps value
4.1.3.12 - SOLO-3013
| Code | SOLO-3013 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a staking transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits staking transactions to configure how accounts and nodes stake, so this means the transaction was rejected or could not be submitted. It is retryable, since a transient network or node-readiness issue often clears on a later attempt.
Troubleshooting Steps
- Verify the treasury account has sufficient HBAR balance.
- Confirm the node is in ACTIVE status: kubectl get pods -n
-l solo.hedera.com/type=network-node - Check gRPC connectivity to the consensus node.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.13 - SOLO-3014
| Code | SOLO-3014 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when the prepare-upgrade transaction fails to execute; when available the underlying failure is wrapped in cause. This transaction stages the upgrade artifacts on the network before a freeze-upgrade, so this means staging was rejected or could not be submitted — for example the upgrade file was not present or valid, or the network could not be reached. It is retryable.
Troubleshooting Steps
- Verify the node admin key is correct and loaded from the k8s secret.
- Confirm the freeze admin account has sufficient HBAR balance.
- Verify the upgrade zip file hash is correct.
- Check node client connection to the consensus network.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.14 - SOLO-3015
| Code | SOLO-3015 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a freeze-upgrade transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits this transaction to freeze the network in preparation for a software upgrade, so this means it was rejected or could not be submitted — for example the prepared upgrade was not staged, the admin key did not sign, or the network could not be reached. It is retryable.
Troubleshooting Steps
- Verify the node admin key is correct and loaded from the k8s secret.
- Confirm the freeze admin account has sufficient HBAR balance.
- Verify the nodes have completed the prepare upgrade step.
- Verify gossip endpoints and gRPC service endpoints are reachable from the network.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.15 - SOLO-3016
| Code | SOLO-3016 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a freeze-only transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits a freeze-only transaction to pause the network (for example before maintenance), so this means the transaction was rejected or could not be submitted. It is retryable, since a transient network or node-readiness problem often clears on a later attempt.
Troubleshooting Steps
- Verify the node admin key is correct and loaded from the k8s secret.
- Confirm the freeze admin account has the correct operator key set.
- Verify the freeze admin account has sufficient HBAR balance.
- Verify gossip endpoints and gRPC service endpoints are reachable from the network.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.16 - SOLO-3017
| Code | SOLO-3017 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the node-update transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits a node-update transaction to change a consensus node’s address-book entry (keys or endpoints), so this means the transaction was rejected or could not be submitted — for example the signing key was wrong, the updated values were invalid, or the network could not be reached.
Troubleshooting Steps
- Verify the node admin key is correct and loaded from the k8s secret.
- Confirm the node client is connected to the consensus network.
- Check if the new account number is valid and funded.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.17 - SOLO-3018
| Code | SOLO-3018 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the node-delete transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits a node-delete transaction to remove a consensus node from the address book, so this means the transaction was rejected or could not be submitted — for example the admin key did not sign, the target node id was invalid, or the network could not be reached.
Troubleshooting Steps
- Verify the node admin key is correct and loaded from the k8s secret.
- Confirm the node exists in the current address book.
- Verify gossip endpoints and gRPC service endpoints are reachable from the network.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.18 - SOLO-3019
| Code | SOLO-3019 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the node-create transaction fails to execute; when available the underlying failure is wrapped in cause. solo submits a node-create transaction to add a consensus node to the network’s address book, so this means the transaction was rejected or could not be submitted — for example the admin key did not sign, the node endpoints or parameters were invalid, or the network could not be reached.
Troubleshooting Steps
- Verify gossip endpoints and gRPC service endpoints are reachable from the network.
- Confirm the admin key is valid and the account has sufficient HBAR.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.19 - SOLO-3021
| Code | SOLO-3021 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot read an account’s HBAR balance from the network via the Hedera SDK; the message names the account and, when present, wraps the underlying cause. solo queries balances to verify funding and confirm operations, so this is raised when the balance query does not return — typically because the target consensus node is unreachable or not yet ACTIVE, or the SDK client is misconfigured. It is retryable, since a transient network or node-readiness issue often clears on a later attempt.
Troubleshooting Steps
- Verify gossip endpoints and gRPC service endpoints are reachable from the network.
- Confirm the account ID is valid and exists on the network.
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.20 - SOLO-3022
| Code | SOLO-3022 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo explorer node add cannot bring up the Hiero Explorer: the Helm release for the explorer chart failed to install, or its pods never reached a Ready state before solo stopped waiting. The original failure is wrapped in cause.message. Typical roots are an explorer image that cannot be pulled, misconfigured chart values (for example an unreachable mirror-node endpoint), a TLS/cert-manager prerequisite that is not ready, or insufficient cluster resources to schedule the pod.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect explorer pods: kubectl get pods -A -l app.kubernetes.io/component=hiero-explorer
- Inspect Helm release: helm status
-n
4.1.3.21 - SOLO-3023
| Code | SOLO-3023 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo explorer node upgrade cannot upgrade the Hiero Explorer; the underlying failure is wrapped in cause. Upgrade re-applies the explorer Helm release at a new chart or version, so this means the upgrade did not succeed — for example a Helm failure, an image that cannot be pulled, or misconfigured values.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect Helm release: helm status
-n - View explorer pod logs: kubectl logs -n
4.1.3.22 - SOLO-3024
| Code | SOLO-3024 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo explorer node destroy cannot tear down the Hiero Explorer; the underlying failure is wrapped in cause. Destroy uninstalls the explorer Helm release and removes its resources, so this means that teardown did not complete — for example a Helm release could not be removed or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List Helm releases: helm list -A
- Force-uninstall if stuck: helm uninstall
-n
4.1.3.23 - SOLO-3025
| Code | SOLO-3025 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo relay node add cannot deploy the JSON-RPC relay; the underlying failure is wrapped in cause. Deploy installs the relay Helm release, so this means that install did not succeed — for example a Helm failure, an image that cannot be pulled, misconfigured values (such as an unreachable network or mirror-node endpoint), or insufficient cluster resources.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect relay pods: kubectl get pods -A -l app.kubernetes.io/instance=relay-
- Inspect Helm release: helm status
-n
4.1.3.24 - SOLO-3026
| Code | SOLO-3026 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo relay node upgrade cannot upgrade the JSON-RPC relay; the underlying failure is wrapped in cause. Upgrade re-applies the relay Helm release at a new chart or version, so this means the upgrade did not succeed — for example a Helm failure, an image that cannot be pulled, or misconfigured values.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect Helm release: helm status
-n - View relay pod logs: kubectl logs -n
4.1.3.25 - SOLO-3027
| Code | SOLO-3027 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo relay node destroy cannot tear down the JSON-RPC relay; the underlying failure is wrapped in cause. Destroy uninstalls the relay Helm release and removes its resources, so this means teardown did not complete — for example a Helm release could not be removed or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List Helm releases: helm list -A
- Force-uninstall if stuck: helm uninstall
-n
4.1.3.26 - SOLO-3028
| Code | SOLO-3028 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a JSON-RPC relay that should be running is not; the message names the release and wraps the underlying failure in cause. solo checks that the relay pods are present and running before relying on it, so this means that check failed. It is retryable, since a relay that is still starting or briefly restarting often recovers on a later attempt.
Troubleshooting Steps
- Check relay pod status: kubectl get pods -A | grep
- View relay pod logs: kubectl logs -n
-l app.kubernetes.io/instance= - Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.27 - SOLO-3029
| Code | SOLO-3029 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a deployed JSON-RPC relay does not become ready in time; the message names the release and wraps the underlying failure in cause. solo waits for the relay pods to reach a Ready state after install, so this means that wait did not succeed in time. It is retryable, since a relay that is merely slow to start often becomes ready on a later attempt; a persistent failure points to a crash-looping or misconfigured relay.
Troubleshooting Steps
- Check relay pod status: kubectl get pods -A | grep
- Describe relay pods to check readiness probe failures: kubectl describe pods -A -l app.kubernetes.io/instance=
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.28 - SOLO-3030
| Code | SOLO-3030 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot retrieve the operator key the JSON-RPC relay needs; the underlying failure is wrapped in cause. The relay signs transactions with an operator account key that solo reads (for example from a secret), so this means that retrieval failed. It is retryable, since a transient cluster or lookup problem often clears on a later attempt.
Troubleshooting Steps
- Verify K8s API connectivity: kubectl get pods -n
- If an operator key secret exists, verify it has a privateKey field: kubectl get secret -n
-o yaml | grep privateKey - Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.29 - SOLO-3031
| Code | SOLO-3031 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo mirror node add cannot deploy the mirror node; the underlying failure is wrapped in cause. Deploy installs the mirror node Helm release (its importer, REST, and database components), so this means that install did not succeed — for example a Helm failure, an image that cannot be pulled, misconfigured values, or insufficient cluster resources.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect mirror node pods: kubectl get pods -A -l app.kubernetes.io/instance=mirror-
- Inspect Helm release: helm status
-n
4.1.3.30 - SOLO-3032
| Code | SOLO-3032 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo mirror node upgrade cannot upgrade the mirror node; the underlying failure is wrapped in cause. Upgrade re-applies the mirror node Helm release at a new chart or version, so this means the upgrade did not succeed — for example a Helm failure, an image that cannot be pulled, or misconfigured values.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect Helm release: helm status
-n - View mirror node pod logs: kubectl logs -n
4.1.3.31 - SOLO-3033
| Code | SOLO-3033 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo mirror node destroy cannot tear down the mirror node; the underlying failure is wrapped in cause. Destroy uninstalls the mirror node Helm release and removes its resources, so this means teardown did not complete — for example a Helm release could not be removed or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List Helm releases: helm list -A
- Force-uninstall if stuck: helm uninstall
-n
4.1.3.32 - SOLO-3034
| Code | SOLO-3034 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot retrieve the operator key the mirror node needs; the underlying failure is wrapped in cause. solo reads the operator account key (for example from a secret) so the mirror node can perform its operations, so this means that retrieval failed. It is retryable, since a transient cluster or lookup problem often clears on a later attempt.
Troubleshooting Steps
- Verify K8s API connectivity: kubectl get pods -n
- If an operator key secret exists, verify it has a privateKey field: kubectl get secret -n
-o yaml | grep privateKey - Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.33 - SOLO-3035
| Code | SOLO-3035 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a one-shot deployment fails; the message describes the failing step and wraps the underlying failure in cause. One-shot mode brings up a complete network in a single command by running many deploy steps in sequence, so this means one of those steps did not succeed — the message identifies which, and common roots are Helm, image, or cluster-resource problems in the underlying step.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- If rollback was skipped, clean up partial resources: solo one-shot single destroy
- If nothing else works, remove the SOLO_HOME directory and delete the cluster:
- +kind delete cluster –name solo-cluster
- rm -rf ~/.solo
4.1.3.34 - SOLO-3036
| Code | SOLO-3036 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when destroying a one-shot deployment fails; the underlying failure is wrapped in cause. One-shot destroy tears down everything a one-shot deploy created, so this means that teardown did not complete — for example a Helm release or cluster could not be removed, or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List remaining Helm releases: helm list -A
- Delete stuck resources manually: kubectl delete
-n
4.1.3.35 - SOLO-3037
| Code | SOLO-3037 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot retrieve information about a one-shot deployment; the underlying failure is wrapped in cause. solo reads deployment details (such as component status and endpoints) to report them, so this means that lookup failed — for example the cluster was unreachable or the expected resources were not found.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify kubeconfig context is valid: kubectl cluster-info
4.1.3.36 - SOLO-3038
| Code | SOLO-3038 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot prepare the Falcon values file used during deployment; the underlying failure is wrapped in cause. solo assembles this Helm values file from configuration and runtime inputs before installing, so this means that preparation step failed — for example a required input was missing or invalid, or the file could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the profile YAML is valid: solo deployment profile validate
4.1.3.37 - SOLO-3039
| Code | SOLO-3039 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo block node add cannot deploy a block node; the underlying failure is wrapped in cause. Deploy installs the block node Helm release, so this means that install did not succeed — for example a Helm failure, an image that cannot be pulled, misconfigured values, or insufficient cluster resources.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Inspect Helm release: helm status
-n - Check Helm history: helm history
-n
4.1.3.38 - SOLO-3040
| Code | SOLO-3040 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo block node destroy cannot tear down a block node; the underlying failure is wrapped in cause. Destroy uninstalls the block node Helm release and removes its resources, so this means teardown did not complete — for example a Helm release could not be removed or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Inspect Helm release: helm status
-n - Check Helm history: helm history
-n
4.1.3.39 - SOLO-3041
| Code | SOLO-3041 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo block node upgrade cannot upgrade a block node; the underlying failure is wrapped in cause. Upgrade re-applies the block node Helm release at a new chart or version, so this means the upgrade did not succeed — for example a Helm failure, an image that cannot be pulled, or misconfigured values.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Inspect Helm release: helm status
-n - Check Helm history: helm history
-n
4.1.3.40 - SOLO-3042
| Code | SOLO-3042 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot register an external block node with the deployment; the underlying failure is wrapped in cause. Adding an external block node records a block node that runs outside this deployment so consensus nodes can use it, so this means that registration step failed — for example the provided endpoint was unreachable or the remote configuration could not be updated.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect the remote config for the registered node: solo deployment config info
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- If the issue persists, report it with your solo log
4.1.3.41 - SOLO-3043
| Code | SOLO-3043 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot remove an external block node from the deployment; the underlying failure is wrapped in cause. Removing an external block node updates the configuration so consensus nodes no longer use it, so this means that removal step failed — for example the remote configuration could not be updated.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect the remote config for the registered node: solo deployment config info
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- If the issue persists, report it with your solo log
4.1.3.42 - SOLO-3044
| Code | SOLO-3044 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a block node health check does not pass; the message states the reason. solo health-checks a block node to confirm it is up and serving before relying on it, so this means the check reported the node unhealthy or could not reach it. It is retryable, since a block node that is still starting often passes on a later attempt.
Troubleshooting Steps
- Check block node pod status: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Verify liveness endpoint manually: kubectl exec -n
– curl http://localhost: /healthz/readyz - Check pod logs: kubectl logs -n
-l block-node.hiero.com/type=block-node - Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.43 - SOLO-3045
| Code | SOLO-3045 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot start a rapid-fire load run; the underlying failure is wrapped in cause. This step launches the load generator against the network, so this means startup failed — for example the load-test workload could not be created or scheduled. It is retryable, since transient cluster issues often clear on a later attempt.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check NLG pod status: kubectl get pods -n
-l app.kubernetes.io/instance=network-load-generator - Describe NLG pods for scheduling or image-pull errors: kubectl describe pods -n
-l app.kubernetes.io/instance=network-load-generator - Check the NLG Helm release: helm status network-load-generator -n
4.1.3.44 - SOLO-3046
| Code | SOLO-3046 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot stop a rapid-fire load run; the underlying failure is wrapped in cause. This step halts the running load generator, so this means the stop did not succeed — for example the workload could not be reached or removed.
Troubleshooting Steps
- Check solo logs for the root cause: tail -n 100 ~/.solo/logs/solo.log
- Check NLG pod status: kubectl get pods -n
-l app.kubernetes.io/instance=network-load-generator - Check for running NLG Java processes: kubectl exec -n
– ps aux | grep java - To force-stop, uninstall the NLG chart: helm uninstall network-load-generator -n
4.1.3.45 - SOLO-3047
| Code | SOLO-3047 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot stop a running rapid-fire load test; the message names the test class and wraps the underlying failure in cause. This step terminates the load generator, so this means the stop did not succeed — for example the load-test pod or process could not be reached or signaled.
Troubleshooting Steps
- Check if the test process is still running: kubectl exec -n
– ps aux | grep - Manually kill the process: kubectl exec -n
– pkill -f - To stop the load test entirely, uninstall the NLG chart: helm uninstall network-load-generator -n
4.1.3.46 - SOLO-3048
| Code | SOLO-3048 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when creating a Hedera account through the SDK fails; the underlying failure is wrapped in cause. solo creates accounts (for example operator or treasury accounts) during network setup, so this means the create transaction did not succeed — commonly because the network rejected it (insufficient payer balance, key problems) or the consensus node could not be reached.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Check node logs for errors: kubectl logs
-n - Create a new account: solo ledger account create
4.1.3.47 - SOLO-3049
| Code | SOLO-3049 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when updating the keys on a Hedera account fails; the message names the account. solo rotates account keys (for example replacing genesis keys) with an update transaction, so this means that transaction did not succeed — commonly because the existing key did not sign correctly, the new key is invalid, or the network rejected or could not be reached.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify the account ID is correct and the account exists on the network
4.1.3.48 - SOLO-3050
| Code | SOLO-3050 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a batch key-update over several accounts does not fully succeed; the message reports how many accounts were not updated. solo updates account keys in bulk during setup and raises this when one or more of those updates is rejected — typically due to signing or key problems on the affected accounts, or transient network failures while submitting the batch.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify operator account has sufficient permissions
- Update individual accounts: solo ledger account update
4.1.3.49 - SOLO-3051
| Code | SOLO-3051 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when an HBAR transfer transaction fails; the underlying failure is wrapped in cause. solo transfers HBAR to fund accounts during setup and account operations, so this means the transfer was rejected or could not be submitted — commonly an insufficient sender balance, a signing problem, or an unreachable consensus node.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify the sender account has sufficient HBAR balance
4.1.3.50 - SOLO-3052
| Code | SOLO-3052 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot retrieve an account’s information from the network via the SDK; the underlying failure is wrapped in cause. It means the account-info query did not return — for example the account does not exist, the consensus node is unreachable or not yet ACTIVE, or the SDK client is misconfigured.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify the account ID exists on the network
4.1.3.51 - SOLO-3053
| Code | SOLO-3053 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when updating a Hedera account’s properties fails; the message names the account. solo submits an account-update transaction to change account settings, so this means that transaction did not succeed — for example the account’s key did not sign, the requested change was invalid, or the network rejected or could not be reached.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify the account exists on the network: solo ledger account update
4.1.3.52 - SOLO-3054
| Code | SOLO-3054 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot store an account’s key material as a Kubernetes secret; the message names the account. After creating or updating an account, solo persists its keys in a cluster secret so other components can use them, so this is raised when that secret cannot be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl get pods -n
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation
4.1.3.53 - SOLO-3055
| Code | SOLO-3055 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot determine the EVM address associated with a Hedera account; the message names the account. solo derives or looks up the account EVM (alias) address for EVM-compatible workflows, so this is raised when that lookup fails — for example the account has no EVM address, or its account info could not be retrieved from the network.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Verify the account ID is valid and the account exists on the network
4.1.3.54 - SOLO-3056
| Code | SOLO-3056 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot configure access to a consensus node; the underlying failure is wrapped in cause. This step establishes the connection (such as a port-forward) and credentials needed to reach a node, so this means that configuration failed — for example the node pod or service was not reachable, or a required port-forward could not be created.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus node pods are running: kubectl get pods -n
- Check node logs: kubectl logs
-n - Restart the consensus node: solo consensus node restart
4.1.3.55 - SOLO-3057
| Code | SOLO-3057 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot load the Hedera SDK client used to talk to the network; the underlying failure is wrapped in cause. The client is built from network and node connection details plus operator credentials, so this means that load step failed — for example the node services or endpoints could not be resolved, or the operator key was missing or invalid.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus node pods are running: kubectl get pods -n
- Inspect node pod logs: kubectl logs
-n - Verify network port-forwards are active: solo deployment port-forwards refresh
4.1.3.56 - SOLO-3058
| Code | SOLO-3058 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot refresh the Hedera SDK client’s view of the network; the underlying failure is wrapped in cause. solo refreshes the client when the network’s nodes or endpoints change, so this means re-resolving the connection details failed — for example node services could not be retrieved or the new endpoints were unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus node pods are running: kubectl get pods -n
- Inspect node pod logs: kubectl logs
-n - Verify network port-forwards are active: solo deployment port-forwards refresh
4.1.3.57 - SOLO-3059
| Code | SOLO-3059 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot set up the Hedera SDK client for the network; the underlying failure is wrapped in cause. Setup wires the client to the network node endpoints and operator account before any SDK calls, so this means that configuration step failed — for example endpoints could not be resolved or operator credentials were missing or invalid.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus node pods are running: kubectl get pods -n
- Check port-forward status: solo deployment port-forwards refresh
- Inspect node logs: kubectl logs
-n
4.1.3.58 - SOLO-3060
| Code | SOLO-3060 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo SDK ping to a network node does not succeed within the allowed retries; the message names the node alias and the number of retries tried. solo pings nodes to confirm they are reachable and responsive before relying on them, and raises this once retries are exhausted. It is retryable because a node that is merely slow to start often responds on a later attempt; a persistent failure points to a node that is down or unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the node pod is running: kubectl get pods -n
-l solo.hedera.com/node-name= - Inspect node logs: kubectl logs
-n - Check port-forward status: solo deployment port-forwards refresh
- Restart the node: solo consensus node restart
4.1.3.59 - SOLO-3061
| Code | SOLO-3061 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot retrieve the Kubernetes services for the network’s consensus nodes; the underlying failure is wrapped in cause. solo reads these services to discover node endpoints, so this means the lookup failed — for example the namespace is wrong, the services do not exist yet, or the Kubernetes API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List Kubernetes services in the namespace: kubectl get svc -n
- Verify consensus nodes are deployed: kubectl get pods -n
4.1.3.60 - SOLO-3062
| Code | SOLO-3062 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot store a consensus node’s gossip keys as a Kubernetes secret; the message names the node alias. Gossip keys secure node-to-node communication and are mounted from a cluster secret, so this means that secret could not be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation in the namespace
- Re-run node setup: solo consensus node setup
4.1.3.61 - SOLO-3063
| Code | SOLO-3063 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot store a generated TLS key as a Kubernetes secret; when available the underlying failure is wrapped in cause. solo persists TLS keys in cluster secrets so components can mount them, so this means the secret could not be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation in the namespace
- Re-run node setup: solo consensus node setup
4.1.3.62 - SOLO-3064
| Code | SOLO-3064 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot generate a TLS key; the message includes the underlying error text. solo generates TLS keys to secure node communication, so this means generation failed — for example the key-generation tooling errored or a working file could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify required key generation tools are available
- Re-run node setup: solo consensus node setup
4.1.3.63 - SOLO-3065
| Code | SOLO-3065 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot generate a node signing key; the underlying failure is wrapped in cause. Signing keys establish a consensus node identity, so this means generation failed — for example the key-generation tooling errored or a working file could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify key generation tools are available
- Re-run key generation: solo keys consensus
4.1.3.64 - SOLO-3066
| Code | SOLO-3066 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot generate the gRPC TLS key for a consensus node; the underlying failure is wrapped in cause. solo generates this key to secure node gRPC traffic, so this means key generation failed — for example the key-generation tooling errored or a working file could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify key generation tools are available
- Re-run node setup: solo consensus node setup
4.1.3.65 - SOLO-3067
| Code | SOLO-3067 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when the gRPC TLS certificate and key supplied by the user do not correspond; the message lists the certificate and key paths. solo pairs each provided certificate with its key for node gRPC TLS, so this means the structures do not match — typically a certificate and key from different pairs, or paths that were swapped or point to the wrong files.
Troubleshooting Steps
- Ensure the number of certificate paths matches the number of key paths
- Each certificate must have a corresponding private key in the same position
- Verify the certificate and key files exist at the specified paths
4.1.3.66 - SOLO-3068
| Code | SOLO-3068 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when the gRPC Web TLS certificate and key supplied by the user do not correspond; the message lists the certificate and key paths. solo pairs each provided certificate with its key for the node’s gRPC Web TLS, so this means the structures do not match — typically a certificate and key from different pairs, or paths that were swapped or point to the wrong files.
Troubleshooting Steps
- Ensure the number of certificate paths matches the number of key paths
- Each certificate must have a corresponding private key in the same position
- Verify the certificate and key files exist at the specified paths
4.1.3.67 - SOLO-3069
| Code | SOLO-3069 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create the TLS certificate secret for a consensus node; the message names the node alias. solo stores node certificates as Kubernetes secrets so they can be mounted, so this means the secret could not be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation
- Re-run node setup: solo consensus node setup
4.1.3.68 - SOLO-3070
| Code | SOLO-3070 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot parse a certificate input the user provided; the message names the input, its type, and the line and index of the offending entry. solo parses each supplied certificate to validate and use it, so this means the content is not valid for the expected format — for example a malformed or truncated certificate, or the wrong kind of file supplied.
Troubleshooting Steps
- Verify the certificate input format is correct for the expected type
- Check the value at line
, position of the input - Ensure certificate values are properly formatted (PEM or DER encoded)
4.1.3.69 - SOLO-3071
| Code | SOLO-3071 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when a certificate file the user referenced does not exist at the given path; the message names the path and input type, with the line and index of the offending entry. solo reads certificate files from the paths provided on the command line or in configuration, so this means the file is missing or the path is wrong — for example a typo, a relative path resolved from an unexpected directory, or a file that was moved.
Troubleshooting Steps
- Verify the file exists at the path:
- Ensure the path is absolute or relative to the working directory
- Check file permissions allow reading the certificate file
4.1.3.70 - SOLO-3072
| Code | SOLO-3072 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create the TLS certificate secret used by the Hiero Explorer; when available the underlying failure is wrapped in cause. The explorer is served over TLS using a certificate stored as a Kubernetes secret, so this means that secret could not be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation
- Re-deploy the explorer: solo explorer node add
4.1.3.71 - SOLO-3073
| Code | SOLO-3073 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a platform file solo needs does not exist; the message names the path. solo reads platform artifacts from expected locations during setup, so this means the file is missing — for example the platform build was incomplete, an earlier download or extract step did not produce it, or the path is wrong.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the file exists at:
- Ensure the node build artifacts are present and the build path is correct
4.1.3.72 - SOLO-3074
| Code | SOLO-3074 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot copy platform files into a consensus node pod; the message names the source files, the pod, and the destination directory, and wraps the underlying failure in cause. solo copies platform artifacts into the node container during setup, so this means the copy failed — for example the pod was not reachable, the destination path was not writable, or the connection dropped mid-copy.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the pod is running: kubectl get pod
-n - Check available disk space in the pod
- Inspect pod logs: kubectl logs
-n
4.1.3.73 - SOLO-3075
| Code | SOLO-3075 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a required key file is missing; the message names the file. solo expects certain key files to be present when provisioning a node, so this means one of them was not found — for example key generation did not produce it, or it was not copied into the expected location.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the key file exists at:
- Re-generate keys if needed: solo keys consensus
- Re-run node setup: solo consensus node setup
4.1.3.74 - SOLO-3076
| Code | SOLO-3076 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot store a genesis account’s admin key as a Kubernetes secret; the message names the account. During genesis setup solo persists admin keys in cluster secrets for later use, so this is raised when that secret cannot be created — for example the namespace is missing, a conflicting secret exists, or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation
- Redeploy the network: solo consensus network deploy
4.1.3.75 - SOLO-3077
| Code | SOLO-3077 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo fails to generate the genesis data used to bootstrap a new network; the underlying failure is wrapped in cause. Genesis generation produces the initial accounts, keys, and configuration the network starts from, so this means that generation step did not complete — for example required inputs were missing or invalid, or a file could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify all consensus node configurations are correct
- Check deployment configuration: solo deployment config info
- Redeploy the network: solo consensus network deploy
4.1.3.76 - SOLO-3078
| Code | SOLO-3078 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot copy the mirror node Postgres initialization script into its container; the message names the namespace and wraps the underlying failure in cause. solo copies this script into the database container before running it, so this means the copy failed — for example the target container or pod was not reachable, or the destination was not writable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the Postgres pod is running: kubectl get pods -n
-l app.kubernetes.io/name=postgresql - Inspect Postgres pod logs: kubectl logs
-n - Re-deploy the mirror node: solo mirror node add
4.1.3.77 - SOLO-3079
| Code | SOLO-3079 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when the mirror node Postgres initialization script fails to run; the message includes the number of attempts made and wraps the underlying failure. solo runs this script to initialize the mirror node database, so this means execution did not succeed across the attempts tried — for example the database was not ready or the script returned an error. It is retryable, since a database that is still starting often accepts the script on a later attempt.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect Postgres pod logs: kubectl logs
-n - Check Postgres pod status: kubectl describe pod
-n - Re-deploy the mirror node: solo mirror node add
4.1.3.78 - SOLO-3080
| Code | SOLO-3080 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the mirror node database owner credential is absent from the expected secret — specifically MIRROR_IMPORTER_DB_OWNER is not present in the mirror-passwords secret. solo reads this secret to obtain the importer’s database owner, so this means the secret exists without the required key, or was not populated as expected during deployment.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect the mirror-passwords secret: kubectl get secret mirror-passwords -n
-o jsonpath="{.data}" - Re-deploy the mirror node to recreate secrets: solo mirror node add
4.1.3.79 - SOLO-3081
| Code | SOLO-3081 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo’s verification of a file’s content fails; the message describes what was being verified. solo verifies file content at certain steps to ensure it matches the expected value, so this means that check did not pass — the content was missing, incomplete, or different from what was required.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running and healthy: kubectl get pods -n
- Inspect node logs for errors: kubectl logs
-n
4.1.3.80 - SOLO-3082
| Code | SOLO-3082 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a Hedera File Service create transaction returns a non-success status; the message includes the network status. solo uses the File Service to store artifacts on the network (such as upgrade files), so this means the file create was rejected — the specific status code identifies why, for example a payer or signature problem or an invalid file.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Consult the Hedera documentation for the meaning of the status code
4.1.3.81 - SOLO-3083
| Code | SOLO-3083 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a Hedera File Service update transaction returns a non-success status; the message includes the network status. solo updates network-stored files (such as upgrade files) via the File Service, so this means the update was rejected — the specific status code identifies why.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Consult the Hedera documentation for the meaning of the status code
4.1.3.82 - SOLO-3084
| Code | SOLO-3084 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a Hedera File Service append transaction returns a non-success status; the message includes the chunk index and the network status. Large files are uploaded in chunks, so this means appending a particular chunk was rejected — the specific status code identifies why, for example a size limit or a payer or signature problem.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Consult the Hedera documentation for the meaning of the status code
4.1.3.83 - SOLO-3085
| Code | SOLO-3085 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a consensus node’s status check returns an empty response. solo queries each node’s status endpoint to determine its state, so an empty reply means the node returned nothing usable — typically because the node is not yet serving its status endpoint, or the request reached a target that is not ready.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the consensus node pod is running: kubectl get pods -n
- Inspect node logs: kubectl logs
-n
4.1.3.84 - SOLO-3086
| Code | SOLO-3086 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a consensus node’s status check response is missing the expected status line. solo parses the status output to read the node’s current state, so this means the response came back but did not contain the line solo needs — usually because the node is still starting and has not produced full status output, or the output format was unexpected.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the consensus node pod is running: kubectl get pods -n
- Inspect node logs: kubectl logs
-n
4.1.3.85 - SOLO-3087
| Code | SOLO-3087 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo fails to create the set of predefined accounts it seeds into a new network; the underlying failure is wrapped in cause. These accounts are created during setup to provide ready-to-use funded accounts, so this means one of those creations did not succeed — commonly a network rejection, a signing or key problem, or an unreachable consensus node.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are running: kubectl get pods -n
- Check node logs for errors: kubectl logs
-n
4.1.3.86 - SOLO-3088
| Code | SOLO-3088 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when content read back from the network does not match what solo uploaded. After uploading a file (for example via the Hedera File Service), solo re-reads it and compares, so this means the round-trip verification failed — the stored content differs from what was sent, indicating the upload was incomplete or corrupted.
Troubleshooting Steps
- Retry the file upload — transient network issues can cause partial or corrupt writes
- Check solo logs for chunk append errors: tail -n 100 ~/.solo/logs/solo.log
- Verify consensus nodes are healthy: kubectl get pods -n
- Check node logs for transaction errors: kubectl logs
-n - Confirm no concurrent process modified the same Hedera file during the upload
4.1.3.87 - SOLO-3089
| Code | SOLO-3089 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot resolve the Kubernetes service for a specific consensus node; the message names the node alias. solo expects each node to expose a service it can reach, so this is raised when no matching service is found — typically because the node alias does not correspond to a deployed node, or the selected deployment or namespace does not contain it.
Troubleshooting Steps
- Verify that node ‘
’ exists in the deployment: solo deployment info - List all node services in the namespace: kubectl get svc -n
- Check that the consensus node pod is running: kubectl get pods -n
-l app= - Check solo logs for more context: tail -n 100 ~/.solo/logs/solo.log
4.1.3.88 - SOLO-3090
| Code | SOLO-3090 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo block node collect-jfr cannot collect the Java Flight Recorder recording from a block node; the underlying failure is wrapped in cause. Retryable, since a transient pod or cluster-API problem often clears on a later attempt.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Verify the block node was deployed with Java Flight Recorder enabled
- Verify the cluster is reachable: kubectl cluster-info –context
4.1.3.89 - SOLO-3091
| Code | SOLO-3091 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot restore a consensus node’s gossip keys from its Kubernetes secret back to the local keys directory; the message names the node alias. When --debug is off the on-disk gossip keys are deleted after they are uploaded to the cluster, so later commands re-fetch them from the secret — this means that secret could not be read or did not contain the expected key files (for example the namespace or secret is missing, or the Kubernetes API rejected the request).
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Confirm the gossip key secret exists: kubectl get secret network-
-keys-secrets -n - Verify RBAC permissions allow reading secrets in the namespace
4.1.3.90 - SOLO-3092
| Code | SOLO-3092 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when the Hedera SDK client reports “failed to find a healthy working node”, meaning the SDK client’s gRPC connections to the consensus network are all marked unhealthy. This refers to the SDK client’s network connectivity, not the consensus node’s platform status — the consensus node itself is often still ACTIVE. The usual culprits are a broken local port-forward tunnel, an HAProxy issue, or a failure in another component whose deployment performs SDK transactions. It is retryable because re-establishing the connection (for example by recreating the port-forward) often resolves it.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the consensus node platform status: solo consensus node states –deployment
–node-aliases - Recreate the port-forwards: solo deployment refresh port-forwards
- Check the HAProxy pods are running: kubectl get pods -n
-l app.kubernetes.io/name=haproxy - If the consensus node is ACTIVE, inspect the other components that were being deployed (for example the JSON-RPC relay or mirror node database): kubectl get pods -n
4.1.3.91 - SOLO-3093
| Code | SOLO-3093 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot load a consensus node key or certificate from its PEM file; the underlying failure is wrapped in cause and the message names the offending file. solo reads the gossip and gRPC TLS PEM files back from disk before using them, so this means the file is missing, truncated, or not valid PEM content — regenerating the keys replaces the corrupt files.
Troubleshooting Steps
- Verify the file exists and contains valid PEM content:
- Regenerate the node keys: solo keys consensus generate –deployment
–generate-gossip-keys –generate-tls-keys - Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.92 - SOLO-3094
| Code | SOLO-3094 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo detects that a consensus node’s container has entered a non-recoverable crash state (e.g. CrashLoopBackOff, OOMKilled) while polling for the node to become active. The underlying process will never recover on its own, so solo fails fast instead of exhausting the full polling timeout.
Troubleshooting Steps
- Check node pod status: kubectl get pods -n
-l solo.hedera.com/node-name= - View previous container logs: kubectl logs -n
-l solo.hedera.com/node-name= –previous - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.3.93 - SOLO-3095
| Code | SOLO-3095 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot store the JSON-RPC relay’s operator credentials as a Kubernetes secret; the message names the secret. Solo passes the relay operator id and key to the relay Helm chart via a pre-created Kubernetes secret rather than plaintext --set values, so this is raised when that secret cannot be created — for example the namespace is missing or the Kubernetes API rejected the request.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl get pods -n
- Check existing secrets: kubectl get secrets -n
- Verify RBAC permissions allow secret creation
4.1.3.94 - SOLO-3096
| Code | SOLO-3096 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | Yes |
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect mirror node importer pods: kubectl get pods -A -l app.kubernetes.io/component=importer
- Verify the mirror node was deployed or upgraded with the Java Flight Recorder values overlay, which runs the importer on the JVM image
- Verify the cluster is reachable: kubectl cluster-info –context
4.1.3.95 - SOLO-3097
| Code | SOLO-3097 |
| Category | Component |
| Ownership | User |
| Retryable | No |
Description
Thrown when a --state-file restore settles some nodes into ACTIVE and others into FREEZE_COMPLETE instead of all nodes reaching the same terminal status; the message lists each node alias with the status it reached. checkAllNodesAreActiveOrFrozen waits for every node to reach one of those two statuses and only skips the ACTIVE-only follow-up work when every node came up frozen, so a mixed result means the nodes disagree about whether the restored snapshot replays back into a freeze — continuing would run the ACTIVE-only checks against a node that can never become ACTIVE without a fresh start, which only fails after burning the full activeness timeout.
Troubleshooting Steps
- Every restored node must reach the same status, ACTIVE or FREEZE_COMPLETE
- Check pod status for the node(s) that disagree: kubectl get pods -n
-l solo.hedera.com/node-name= - Review node logs: kubectl logs -n
-l solo.hedera.com/node-name=
4.1.3.96 - SOLO-3098
| Code | SOLO-3098 |
| Category | Component |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo has rotated a consensus node’s admin key on the network but could not save the new key in the node’s admin key secret, even after retrying. The network already requires the new key, so solo writes the secret to a recovery manifest (or prints it, when even that fails) and this error says how to apply it. The key is never part of this error, which is written to the solo log. Without that secret every later rotation of the node fails with INVALID_SIGNATURE.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify RBAC permissions allow secret creation in the namespace
- Recreate the secret:
apply -f - Delete
once the secret exists, as it holds the private keyRecreate the secret: save the printed manifest to a file and run apply -f
4.1.4 - Validation
4.1.4.1 - SOLO-4001
| Code | SOLO-4001 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when code reaches a point that requires a value but the value is absent or empty; the error message describes the argument that was expected. In most cases this is a required CLI flag or configuration value that the command was invoked without (for example a deployment selection left empty). It is also used as an internal guard when a method is called without a mandatory argument, in which case it points to a defect in the calling code rather than to user input.
Troubleshooting Steps
- Provide the missing argument. Run solo –help for usage information
4.1.4.2 - SOLO-4002
| Code | SOLO-4002 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an argument value is not legal for the operation; the message states the reason, and the offending value is attached. solo validates argument values before using them, so this means a provided value was out of range, malformed, or otherwise unacceptable.
Troubleshooting Steps
- An argument has an valid value or format.
- Verify the argument value before retrying
4.1.4.3 - SOLO-4003
| Code | SOLO-4003 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an output format is not one of the allowed values; the message names the offending value and the allowed set (json, yaml, wide). solo formats command output according to this flag, so this means an unsupported value was supplied.
Troubleshooting Steps
- Valid output formats are: json, yaml, wide
4.1.4.4 - SOLO-4004
| Code | SOLO-4004 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the consensus node count flag is required but missing; the message names the flag and the phase in which it is needed. solo needs to know how many consensus nodes to act on, so this means the flag must be supplied at that phase.
Troubleshooting Steps
- Specify the number of consensus nodes using the –
flag, e.g. – 3
4.1.4.5 - SOLO-4005
| Code | SOLO-4005 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown while validating a port value supplied through a CLI flag or configuration field, when the value does not denote a usable TCP/UDP port: it is not an integer, or it falls outside the valid range of 1–65535. The error message echoes the offending value. This is raised before solo tries to bind, forward, or configure the port, so it reflects bad input (a typo, a non-numeric string, or 0/a negative/too-large number) rather than a port that is already in use.
Troubleshooting Steps
- Port numbers must be integers between 1 and 65535
4.1.4.6 - SOLO-4006
| Code | SOLO-4006 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a local build path does not exist; the message names it. solo reads platform artifacts from this path, so this means it is missing or the path is wrong.
Troubleshooting Steps
- Verify the path exists: ls -la
- Set the correct path: solo consensus node setup –local-build-path
- Build the platform locally and point to the data/ directory output
4.1.4.7 - SOLO-4007
| Code | SOLO-4007 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a local build path is missing the required apps and lib subdirectories; the message names the path. solo expects a local platform build to contain both, so this means the path does not point at a complete build.
Troubleshooting Steps
- Verify the directory structure: ls -la
- Ensure the path points to the data/ directory of the Hedera platform build
- Expected layout:
/apps/.jar and /lib/ .jar (set via –local-build-path)
4.1.4.8 - SOLO-4008
| Code | SOLO-4008 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when no jar files are found in a local build subdirectory; the message names the subdirectory. solo expects the build subdirectories to contain jars, so this means the build is incomplete or the path is wrong.
Troubleshooting Steps
- List files in the directory: ls -la
- Ensure a complete platform build was performed before using –local-build-path
- Expected:
/apps/HederaNode.jar and /lib/*.jar
4.1.4.9 - SOLO-4009
| Code | SOLO-4009 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when no JAR files are found in the expected directory inside a node container; the message names the node alias and the directory. The platform software should have been copied to the node before starting it, so their absence indicates an internal ordering or setup defect and is treated as an internal Solo error.
Troubleshooting Steps
- Run setup before starting: solo consensus node setup
- Verify the directory inside the pod: kubectl exec
-n – ls - Re-copy platform software: solo consensus node setup –local-build-path
4.1.4.10 - SOLO-4010
| Code | SOLO-4010 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when --grpc-endpoints is required for the chosen endpoint type but was not provided; the message names the endpoint type. Certain endpoint types need explicit gRPC endpoints, so this means the flag must be supplied for that type.
Troubleshooting Steps
- Provide gRPC endpoints: solo consensus node add –grpc-endpoints ip:port,...
- Or switch endpoint type: solo consensus node add –endpoint-type FQDN
- Review flag usage: solo consensus node add –help
4.1.4.11 - SOLO-4011
| Code | SOLO-4011 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an output directory is required but --output-dir was not set. solo exports context data to this directory, so this means the flag must be provided.
Troubleshooting Steps
- Provide the output directory: solo node
–output-dir - Run with –help to see required flags: solo node
–help
4.1.4.12 - SOLO-4012
| Code | SOLO-4012 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an input directory is required but --input-dir was not set. solo reads context data from this directory, so this means the flag must be provided.
Troubleshooting Steps
- Provide the input directory: solo node
–input-dir - Run with –help to see required flags: solo node
–help
4.1.4.13 - SOLO-4013
| Code | SOLO-4013 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the WRAPs key path does not exist; the message names the path. solo reads the WRAPs key from this path, so this means it is missing or the path is wrong.
Troubleshooting Steps
- Verify the path: ls -la
- Set the correct path: solo consensus node add –wraps-key-path
- Or omit the flag to download WRAPs keys automatically
4.1.4.14 - SOLO-4014
| Code | SOLO-4014 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a configuration file referenced by a flag does not exist; the message names the flag and the absolute and relative paths tried. solo reads the file from the provided path, so this means it is missing or the path is wrong — for example a typo or a relative path resolved from an unexpected directory.
Troubleshooting Steps
- Verify the file exists: ls -la
- Set the correct file path for the –
flag - Run with –help for configuration file flags: solo consensus node setup –help
4.1.4.15 - SOLO-4015
| Code | SOLO-4015 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the consensus node version saved in the remote config differs from the requested version; the message names both. solo guards against mixing versions, so this means the requested version does not match what the deployment recorded — align the versions.
Troubleshooting Steps
- Check the saved version: solo deployment config info –deployment
- Use the same version: solo consensus node setup –release-tag
- Or upgrade the network first: solo consensus network upgrade –upgrade-version
4.1.4.16 - SOLO-4016
| Code | SOLO-4016 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a requested upgrade version does not exist; the message names the version. solo looks up upgrade versions before using them, so this means the version is not available — for example a wrong or not-yet-published version.
Troubleshooting Steps
- Check valid release versions: https://github.com/hashgraph/hedera-services/releases
- Use a published release tag: solo consensus network upgrade –upgrade-version v0.x.y
4.1.4.17 - SOLO-4017
| Code | SOLO-4017 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an operation needs PVCs but the PVCs flag is not enabled. Adding a node requires persistent storage, so this means PVCs must be enabled first.
Troubleshooting Steps
- Redeploy with PVCs enabled: solo consensus network deploy –pvcs true
- Check the current deployment configuration: solo deployment config info –deployment
- PVCs are required for node add operations to persist state across pod restarts
4.1.4.18 - SOLO-4018
| Code | SOLO-4018 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo would need to prompt for input but is running non-interactively. A required value was not supplied and solo cannot ask for it (for example in CI or with prompts disabled), so provide the missing value explicitly (such as via the deployment flag).
Troubleshooting Steps
- Provide required flags explicitly instead of relying on interactive prompts
- Use
to specify the deployment name - Run with –help to see all available flags: solo consensus node –help
4.1.4.19 - SOLO-4020
| Code | SOLO-4020 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when --wraps is used with a consensus node version below the minimum required; the message names the minimum version. WRAPs support requires a sufficiently new node version, so this means the selected version is too old.
Troubleshooting Steps
- Upgrade consensus node first: solo consensus network upgrade –upgrade-version
- Or disable WRAPs: solo consensus network deploy –wraps false
4.1.4.20 - SOLO-4021
| Code | SOLO-4021 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the provided state file path does not exist; the message names the path (or notes it was not specified). solo needs a valid path to the state file, so this means the path is missing or wrong.
Troubleshooting Steps
- Verify the path exists: ls -la <path ?? ‘
'> - Download a valid state file first: solo consensus state download
- Then provide either the downloaded .zip file or the download parent directory using –state-file
- When a directory is provided, Solo looks for state files under:
/states/ /
4.1.4.21 - SOLO-4022
| Code | SOLO-4022 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a state file does not exist or is not a regular file; the message names the path. solo reads saved state from this file, so this means it is missing or the path points at something that is not a file.
Troubleshooting Steps
- Verify the file exists and is a regular file: ls -la
- Make sure the path points to a .zip file, not a directory or missing symlink target.
- Download a valid state file first: solo consensus state download
- When using a directory, pass the parent directory; Solo looks under
/states/ / .
4.1.4.22 - SOLO-4023
| Code | SOLO-4023 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a state file is not a .zip; the message names the path. solo expects saved state as a zip archive, so this means a non-zip file was supplied.
Troubleshooting Steps
- Use a state file ending in .zip with –state-file <stateFile.zip>
- Download a valid state file first: solo consensus state download
- If passing a directory instead, Solo will select node-specific state files from
/states/ / .
4.1.4.23 - SOLO-4024
| Code | SOLO-4024 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a state zip file name is invalid; the message names it. solo expects state zip files to follow a specific naming convention, so this means the name does not match it.
Troubleshooting Steps
- Download a valid state file first: solo consensus state download
- Or rename the state zip file to use only letters, numbers, dots, underscores, and hyphens.
- The file name must not start with a hyphen and must not contain slashes, spaces, shell syntax, or path traversal.
- Example valid name: node1-state.zip
4.1.4.24 - SOLO-4025
| Code | SOLO-4025 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an explorer component id is not valid; the message includes the value and its runtime type. solo expects component ids in a specific form, so this means the supplied id is malformed or of the wrong type.
Troubleshooting Steps
- Inspect remote config state for corruption: kubectl get configmap solo-remote-config -n
-o yaml - Check solo logs for config loading errors: tail -n 100 ~/.solo/logs/solo.log
- If the issue persists, this may be an internal bug — report it with your solo log
4.1.4.25 - SOLO-4026
| Code | SOLO-4026 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a relay component id is not valid; the message includes the value and its runtime type. solo expects component ids in a specific form, so this means the supplied id is malformed or of the wrong type.
Troubleshooting Steps
- Inspect remote config state for corruption: kubectl get configmap solo-remote-config -n
-o yaml - Check solo logs for config loading errors: tail -n 100 ~/.solo/logs/solo.log
- If the issue persists, this may be an internal bug — report it with your solo log
4.1.4.26 - SOLO-4028
| Code | SOLO-4028 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a mirror node component id is not valid; the message includes the value and its runtime type. solo expects component ids in a specific form, so this means the supplied id is malformed or of the wrong type.
Troubleshooting Steps
- Inspect remote config state for corruption: kubectl get configmap solo-remote-config -n
-o yaml - Check solo logs for config loading errors: tail -n 100 ~/.solo/logs/solo.log
- If the issue persists, this may be an internal bug — report it with your solo log
4.1.4.27 - SOLO-4029
| Code | SOLO-4029 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a local block node image with the given tag does not exist; the message names the tag. solo expects the referenced local image to be present (for example built or loaded into the cluster), so this means it is missing — build or load the image, or correct the tag.
Troubleshooting Steps
- Verify the image exists locally: docker images | grep
- Pull the image if missing: docker pull
/block-node: - Ensure the tag is a valid semantic version
4.1.4.28 - SOLO-4030
| Code | SOLO-4030 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a block node component id is not the expected type or format; the message includes the value and its runtime type. solo expects component ids in a specific form, so an invalid value passed internally points to a defect in the calling code and is treated as an internal Solo error.
Troubleshooting Steps
- Inspect remote config for corruption: kubectl get configmap solo-remote-config -n
-o yaml - Check solo logs for config loading errors: tail -n 100 ~/.solo/logs/solo.log
- If the issue persists, this may be an internal bug — report it with your solo log
4.1.4.29 - SOLO-4033
| Code | SOLO-4033 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an HBAR amount is invalid; the message includes the offending value. solo parses HBAR amounts from flags and config, so this means the value is not a valid amount — for example non-numeric, or negative where it is not allowed.
Troubleshooting Steps
- Provide a valid positive numeric HBAR amount (e.g., 100 or 0.5)
- Run solo ledger account create –help for usage information
4.1.4.30 - SOLO-4034
| Code | SOLO-4034 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a file ID is not in the expected 0.0.<number> format; the message includes the offending value and an example. solo parses Hedera file IDs from input, so this means the value is malformed.
Troubleshooting Steps
- Provide a file ID in the format 0.0.
(e.g., 0.0.150) - Run solo ledger file –help for usage information
4.1.4.31 - SOLO-4035
| Code | SOLO-4035 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an endpoint is not in the expected url:port format; the message includes the offending value. solo parses endpoints from flags and config, so this means the value is malformed — provide it as url:port.
Troubleshooting Steps
- Provide the endpoint in url:port format (e.g., 127.0.0.1:50211)
- Run solo –help for usage information
4.1.4.32 - SOLO-4036
| Code | SOLO-4036 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an input is not a valid comma-separated string; the message includes the offending value. solo parses comma-separated lists from flags and config, so this means the value could not be parsed as such — for example stray separators or empty entries.
Troubleshooting Steps
- Provide a comma-separated list of values (e.g., node1,node2,node3)
- Do not include spaces around commas unless they are part of the values
4.1.4.33 - SOLO-4037
| Code | SOLO-4037 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a numeric configuration value cannot be parsed; the message names the value and wraps the underlying failure in cause. solo expects a number here, so this means the provided value is not numeric or is not in the accepted form.
Troubleshooting Steps
- Provide a valid integer or decimal number for this configuration option
- Run solo –help for usage information
4.1.4.34 - SOLO-4038
| Code | SOLO-4038 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a storage type value is invalid; the message includes the offending value. solo accepts a fixed set of storage types, so this means the supplied value is not one of them.
Troubleshooting Steps
- Provide a valid storage type value
- Run solo –help for usage information and supported storage types
4.1.4.35 - SOLO-4039
| Code | SOLO-4039 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a flag is declared with a field type solo does not support; the message names the flag and the field type. solo maps flag field types to handling logic, so an unsupported type indicates an internal flag-definition defect and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.36 - SOLO-4040
| Code | SOLO-4040 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an upgrade target version is older than the currently deployed version; the message names the component, the target and current versions, and the flag to use. solo blocks downgrades to prevent accidental rollbacks, so this means the requested version is too old — choose a version equal to or newer than the deployed one.
Troubleshooting Steps
- Specify a version equal to or newer than the currently deployed version (
) using - Downgrades are not supported — check the available releases before upgrading
4.1.4.37 - SOLO-4041
| Code | SOLO-4041 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the number of admin public keys provided does not match the number of consensus nodes; the message reports both counts. solo expects one DER-encoded ED25519 public key per node, so this means the supplied comma-separated list is the wrong length — provide exactly one key per node.
Troubleshooting Steps
- Provide exactly
comma-separated DER encoded ED25519 public keys, one for each consensus node - Run solo consensus network deploy –help for usage information
4.1.4.38 - SOLO-4042
| Code | SOLO-4042 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a component being added already exists in the remote configuration; the message names the component id. solo expects to add each component once, so a duplicate id at this point indicates an internal bookkeeping defect and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.39 - SOLO-4043
| Code | SOLO-4043 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a component id is required but was not provided; the message echoes the value. solo needs an id to locate or record a component, so a missing value passed internally points to a defect in the calling code and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.40 - SOLO-4044
| Code | SOLO-4044 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a component cannot be found during an operation; the message names the component id, its type, and the operation attempted. solo expected the component to be present at this point, so its absence indicates an internal inconsistency and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.41 - SOLO-4045
| Code | SOLO-4045 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a component of a given type and id is not present in the remote configuration; the message names both. solo expected the component to be recorded, so its absence here indicates an internal inconsistency and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.42 - SOLO-4046
| Code | SOLO-4046 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo encounters a component type it does not recognize; the message names the type and, when present, the component id. solo dispatches on known component types, so an unknown value indicates an internal inconsistency and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.43 - SOLO-4047
| Code | SOLO-4047 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a configuration file is empty or contains invalid content. solo reads this file to drive a command, so this means it had no usable content — for example an empty file or content that does not match the expected format.
Troubleshooting Steps
- Verify the configuration file is a valid YAML or JSON document
- Check that the file is not empty and contains the expected fields
- Run solo config ops backup to export a valid configuration for reference
4.1.4.44 - SOLO-4048
| Code | SOLO-4048 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when several clusters are available but none was selected; the message lists them. solo cannot guess which cluster to use, so it asks you to disambiguate with --cluster-ref.
Troubleshooting Steps
- Specify the cluster reference using the –cluster-ref flag
- List available cluster references: solo cluster-ref config list
4.1.4.45 - SOLO-4049
| Code | SOLO-4049 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the cache is used before it has been materialized. solo requires the cache to be populated before it can be read, so this means a read happened too early in the workflow — materialize the cache first.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Run the cache pull step before using cached images: solo cache image –help
4.1.4.46 - SOLO-4050
| Code | SOLO-4050 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a cache image template key is not recognized; the message names the key. solo resolves image versions against a known set of template keys, so this means the supplied key is not one of them — for example a typo or an unsupported template.
Troubleshooting Steps
- Verify the cache image template key is correct in your configuration
- Declare the template in the templates section before using it in version fields
4.1.4.47 - SOLO-4052
| Code | SOLO-4052 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a resolved path falls outside the allowed base directory; the message names the resolved path and the base. solo blocks path traversal for safety, so this means the supplied path escaped the permitted directory — for example .. segments or an absolute path outside the base.
Troubleshooting Steps
- Provide a path that is within the allowed base directory
- Avoid using “..” path components that escape the base directory
4.1.4.48 - SOLO-4053
| Code | SOLO-4053 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a node-aliases value is not an array of strings where one was required. solo expects this value to already be normalized to an array internally, so a non-array here points to a defect in the calling code and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.49 - SOLO-4054
| Code | SOLO-4054 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot resolve a node ID from a node alias; the message names the alias. solo maps aliases to node IDs, so this means the alias is not recognized — for example a typo or an alias not present in the deployment.
Troubleshooting Steps
- Verify the node alias ‘
’ is registered in the current deployment - Check registered nodes: solo deployment config info
4.1.4.50 - SOLO-4055
| Code | SOLO-4055 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot infer a node alias from address data; the message includes the offending data. solo derives aliases from address-book data, so this means the data did not yield a usable alias — for example a malformed or unexpected entry.
Troubleshooting Steps
- Verify the address data format is correct
- Ensure the address book contains valid node alias information
4.1.4.51 - SOLO-4056
| Code | SOLO-4056 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot parse a node alias from input; the message includes the offending value. solo parses node aliases from flags and config, so this means the value could not be parsed as an alias.
Troubleshooting Steps
- Verify the node alias format (expected: node
where N is a positive integer) - Check deployment configuration for valid node aliases: solo deployment config info
4.1.4.52 - SOLO-4057
| Code | SOLO-4057 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo cannot parse a domain name from the provided data; the message includes the offending input. solo parses domain names from configuration and flags, so this means the value is not a parseable domain — for example a malformed or empty value.
Troubleshooting Steps
- Verify the domain name format is correct
- Check the address book configuration for valid domain names
4.1.4.53 - SOLO-4058
| Code | SOLO-4058 |
| Category | Validation |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a template references a dependency solo does not know; the message names the dependency. Templates may only reference declared dependencies, so an unknown one indicates an internal template defect and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.4.54 - SOLO-4059
| Code | SOLO-4059 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when no consensus nodes are found to operate on. solo derives the node set from the deployment and --node-aliases, so this means neither yielded any nodes — check your deployment or the --node-aliases input.
Troubleshooting Steps
- Verify the deployment has consensus nodes configured: solo deployment config info
- Deploy consensus nodes: solo consensus node setup
- Use –node-aliases to specify target nodes explicitly
4.1.4.55 - SOLO-4060
| Code | SOLO-4060 |
| Category | Validation |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a Kubernetes service is not the expected network-node service; the message names the service. solo expects a service of a specific kind when resolving node endpoints, so this means the service exists but is of the wrong type — indicating an unexpected cluster state.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect Kubernetes services: kubectl get svc -n
- Verify the network is deployed correctly: solo consensus network deploy
4.1.4.56 - SOLO-4061
| Code | SOLO-4061 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup configuration file does not exist; the message names the path. solo reads this file to run a backup or restore, so this means it is missing or the path is wrong — for example a typo or a file that was moved.
Troubleshooting Steps
- Verify the configuration file exists at:
- Export a new backup to generate a configuration file: solo config ops backup
4.1.4.57 - SOLO-4062
| Code | SOLO-4062 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup configuration file is empty or invalid. solo reads this file to drive a backup or restore, so this means it contained no usable configuration — for example an empty file or content that does not match the expected format.
Troubleshooting Steps
- Verify the configuration file is a valid YAML or JSON document and is not empty
- Export a new backup to generate a valid configuration file: solo config ops backup
4.1.4.58 - SOLO-4063
| Code | SOLO-4063 |
| Category | Validation |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot read the backup configuration file; the message names the path and wraps the underlying failure in cause. solo reads this file during restore, so this means it could not be read — for example missing permissions or an I/O error.
Troubleshooting Steps
- Verify the file exists and is readable:
- Check file permissions
- Export a new backup to regenerate the configuration file: solo config ops backup
4.1.4.59 - SOLO-4064
| Code | SOLO-4064 |
| Category | Validation |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the backup ConfigMap does not contain a required key; the message names the missing key. solo reads specific keys from the backup ConfigMap during restore, so this means the ConfigMap exists but is missing data it needs — indicating an incomplete or unexpected backup source.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the Kubernetes ConfigMap contains the expected data
- Re-export the backup to regenerate the ConfigMap: solo config ops backup
4.1.4.60 - SOLO-4065
| Code | SOLO-4065 |
| Category | Validation |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot parse the backup configuration; the underlying failure is wrapped in cause. solo parses the backup configuration to drive a restore, so this means the content could not be parsed — for example malformed YAML or an unexpected structure.
Troubleshooting Steps
- Verify the backup configuration file is valid YAML or JSON
- Check that the configuration was exported with a compatible Solo version
- Re-export the backup to regenerate the configuration: solo config ops backup –deployment
4.1.4.61 - SOLO-4066
| Code | SOLO-4066 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup input directory does not exist; the message names it. solo reads backup data from this directory during restore, so this means it is missing or the path is wrong.
Troubleshooting Steps
- Verify the directory exists at:
- Use –input-dir to specify the correct path to the backup directory
- Run solo config ops restore-clusters –help for usage information
4.1.4.62 - SOLO-4067
| Code | SOLO-4067 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup input directory contains no per-cluster directories; the message names the directory. A valid backup groups data under cluster directories, so this means none were found — the directory is not a valid backup or is empty.
Troubleshooting Steps
- Verify the input directory contains cluster subdirectories:
- Ensure you are pointing to the correct backup directory
- Re-export the backup: solo config ops backup
4.1.4.63 - SOLO-4068
| Code | SOLO-4068 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a backup input directory does not contain the expected solo-remote-config.yaml; the message names the path and the expected <input-dir>/<cluster-ref>/configmaps/solo-remote-config.yaml structure. solo validates the backup layout before restoring, so this means the directory is not a valid backup or the wrong path was given.
Troubleshooting Steps
- Verify the backup archive was exported with compatible Solo and cluster versions
- Check cluster references: solo cluster-ref config list
- Re-export the backup from the original cluster: solo config ops backup
4.1.4.64 - SOLO-4069
| Code | SOLO-4069 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup configuration file contains no cluster information. solo reads cluster details from the backup config to restore, so this means that section is missing or empty — indicating an incomplete or invalid backup config.
Troubleshooting Steps
- Verify the backup configuration file contains cluster information
- Ensure the backup was exported with a compatible Solo version
- Re-export the backup: solo config ops backup
4.1.4.65 - SOLO-4070
| Code | SOLO-4070 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the deployment state to restore contains no components. solo restores components recorded in the backup, so this means none were found to restore — for example an empty or incomplete backup.
Troubleshooting Steps
- Verify the backup archive contains component state information
- Ensure the backup was exported from a deployment with active components
- Re-export the backup: solo config ops backup
4.1.4.66 - SOLO-4071
| Code | SOLO-4071 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the restore options file does not exist; the message names it. solo reads restore options from this file, so this means it is missing or the path is wrong.
Troubleshooting Steps
- Verify the options file exists at:
- Run solo config ops restore-network –help for usage information
4.1.4.67 - SOLO-4072
| Code | SOLO-4072 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when --zip-password is used without --zip-file. A password applies to a specific zip archive, so this means the required --zip-file was not provided — supply it or omit the password.
Troubleshooting Steps
- Provide the –zip-file flag when using –zip-password
- Run solo config ops restore-clusters –help for usage information
4.1.4.68 - SOLO-4073
| Code | SOLO-4073 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the backup input path does not exist; the message names it. solo reads the backup from this path, so this means it is missing or the path is wrong.
Troubleshooting Steps
- Verify the input path exists:
- Use –input-dir or –zip-file to specify the correct backup path
- Run solo config ops restore-clusters –help for usage information
4.1.4.69 - SOLO-4074
| Code | SOLO-4074 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when --zip-password is used but the input path is not a .zip file. A password only applies to a zip archive, so this means the supplied input is not a zip — provide a .zip file or omit the password.
Troubleshooting Steps
- Provide a .zip archive as the input path when using –zip-password
- Run solo config ops restore-clusters –help for usage information
4.1.4.70 - SOLO-4075
| Code | SOLO-4075 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when no log files are found to restore for a context; the message names the context. solo restores log files captured in the backup, so this means none were present for that context.
Troubleshooting Steps
- Verify the backup archive contains log files for context ‘
’ - Check the backup directory structure for expected log files
- Re-export the backup to include log files: solo config ops backup
4.1.4.71 - SOLO-4076
| Code | SOLO-4076 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when input validation for a flag fails; the message names the flag and wraps the underlying failure in cause. solo validates and coerces flag inputs before using them, so this means the provided value did not pass validation — correct the flag value.
Troubleshooting Steps
- Verify the value provided for –
is valid - Run solo –help for usage information and accepted flag values
4.1.4.72 - SOLO-4077
| Code | SOLO-4077 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an action requires interactive confirmation but solo cannot ask for it (for example when running with –quiet or –force, or in a non-interactive environment such as CI). Rather than proceed without the user’s consent, solo refuses and asks the user to confirm interactively.
Troubleshooting Steps
- Re-run the command interactively (without –quiet or –force) so the confirmation prompt can be shown
4.1.4.73 - SOLO-4078
| Code | SOLO-4078 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the values file supplied to --values-file does not exist. solo reads this YAML file to populate per-component configuration before deploying, so this means the path is missing or wrong — for example a typo in the file name or a relative path resolved from an unexpected directory.
Troubleshooting Steps
- Verify the file exists: ls -la
- Check the path passed to –values-file for typos and for the correct file extension (.yaml)
- Relative paths are resolved against the current working directory
4.1.4.74 - SOLO-4079
| Code | SOLO-4079 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a Helm values file cannot be parsed; the underlying failure is wrapped in cause. solo reads values files supplied via --values-file and values files it caches under the solo home directory before handing them to Helm, so this means the file content is neither valid JSON nor valid YAML — for example a stale or partially written cached values file left behind by an interrupted run.
Troubleshooting Steps
- Open
and correct the syntax reported above - {{be rewritten in block style or have all of its keys and string values quoted
- Regenerate a cached values file by deleting it and re-running the command: rm
- Cached values files live under the solo home directory (default ~/.solo) and are rewritten on the next run
4.1.4.75 - SOLO-4080
| Code | SOLO-4080 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the external database dump file is missing from the restore input directory; the message names the expected path. The backup must be created with –backup-external-database for this path to exist.
Troubleshooting Steps
- Re-run the backup with –backup-external-database to include the database dump
- Verify the restore input path points to an extracted backup directory, not a zip file
- Expected dump file location:
4.1.4.76 - SOLO-4081
| Code | SOLO-4081 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the value supplied for a flag does not satisfy the rules that flag declares — for example a namespace that is not a valid DNS label, a node alias that is not of the form node<number>, or a count below its minimum. The message names the flag, the rejected value and the requirement it broke. solo checks flag values before doing any work, so nothing has been changed on the cluster — correct the value and re-run.
Troubleshooting Steps
- Correct the value passed to –
- Run solo –help for usage information and accepted flag values
4.1.4.77 - SOLO-4082
| Code | SOLO-4082 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when –transplant is supplied without –state-file. A transplant replaces the roster carried by a state captured on a different network, so without a state file there is nothing to transplant and the flag would silently have no effect.
Troubleshooting Steps
- Pass the state captured on the other network, e.g. –transplant –state-file <path-to-state.zip>
- Omit –transplant when restoring a network from its own state, which must keep the roster in that state
4.1.4.78 - SOLO-4083
| Code | SOLO-4083 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the selected component versions would run together in a combination the network does not support (for example a block node too old to verify the blocks a consensus node produces); the message lists every broken constraint and names the component to bump. Running such a combination typically fails block verification or ingestion, so choose versions that satisfy the listed minimums, or pass –force to deploy them anyway.
Troubleshooting Steps
- <remedies.join('
- ‘)>
- Upgrade the lagging component first when the rule allows it
- When the consensus node and another component must move together, stage the consensus node upgrade with –skip-node-start, upgrade the other component, then run solo consensus node start
- Or bypass this check with –force if you accept the resulting failures
4.1.4.79 - SOLO-4084
| Code | SOLO-4084 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a docker save archive’s manifest.json does not list the image reference passed via --component-image. Loading such an archive succeeds, but the deployed pod then fails much later with ErrImageNeverPull since the requested tag was never actually loaded into the Kind cluster.
Troubleshooting Steps
- Pass the exact image reference reported by
docker savein –component-image - Re-create the archive with
docker save <image>:<tag> -o <archive>using the intended tag
4.1.4.80 - SOLO-4085
| Code | SOLO-4085 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the operator’s Solo config file exists but cannot be read or parsed. The file is absent for most users and its absence is not an error; reaching this means a file is present and unusable, which must be reported rather than ignored — silently continuing would leave an operator believing their configured settings had been applied.
Troubleshooting Steps
- Check that
is valid YAML - Verify the file is readable by the current user
- Remove the file to fall back to Solo defaults
4.1.4.81 - SOLO-4086
| Code | SOLO-4086 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the operator’s Solo config file cannot be trusted because of its ownership or type. That file selects which additional parent environment variables are forwarded to helm and kubectl, so anyone able to write it can widen what those commands receive; honouring a file Solo does not control would make the setting an escalation path rather than a convenience.
Troubleshooting Steps
- Make the file a regular file owned by the current user: chown “$(id -un)”
- Remove group and other write access: chmod 600
- Apply the same to the containing directory, typically ~/.solo
- Remove the file to fall back to Solo defaults
4.1.4.82 - SOLO-4087
| Code | SOLO-4087 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the operator’s Solo config file parses as YAML but a value has the wrong shape — most often a bare string where a list of environment variable names is expected, which would otherwise be iterated character by character and silently allowlist single letters.
Troubleshooting Steps
- s entry as a YAML list, for example:
- " + + + + +
4.1.4.83 - SOLO-4088
| Code | SOLO-4088 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a post-upgrade system file flag is combined with –upgrade-zip-file; the message names the flag. solo only adds these files to the upgrade zip it builds itself, so with a user-supplied zip the flag would be silently ignored.
Troubleshooting Steps
- Remove –upgrade-zip-file to let solo build the upgrade zip with the –
file - Or remove –
and place the file under data/config/ inside your upgrade zip
4.1.4.84 - SOLO-4089
| Code | SOLO-4089 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a post-upgrade system file flag is used with an –upgrade-version older than the first consensus node release that applies that file; the message names the flag and both versions. Older nodes never read the file, so the upgrade would succeed without changing the system file.
Troubleshooting Steps
- Upgrade to consensus node
or later to apply this file - Or remove –
; this consensus node version ignores the file
4.1.4.85 - SOLO-4090
| Code | SOLO-4090 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an upgrade would move a running component across a version boundary that cannot be crossed in place (for example a consensus node TSS library change that does not convert existing keys or proofs); the message names the component, both versions and the reason. The network has to be destroyed and redeployed at the target version instead, which discards its state.
Troubleshooting Steps
- Destroy the network and deploy it again at
: solo consensus network destroy, then solo consensus network deploy - Redeploying discards the ledger state, so export anything you still need first
- Or bypass this check with –force to exercise the upgrade path itself; the upgraded network is not expected to work
4.1.4.86 - SOLO-4091
| Code | SOLO-4091 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the NETWORK_NODE_LIFECYCLE_MODE environment variable holds a value other than solo-container or consensus-node-image. The message names the rejected value and the accepted ones. solo checks the mode before building any consensus node commands, so nothing has been changed on the cluster — correct the value and re-run.
Troubleshooting Steps
- Set NETWORK_NODE_LIFECYCLE_MODE to one of: <acceptedModes.join(’, ‘)>
- Unset NETWORK_NODE_LIFECYCLE_MODE to use the default solo-container image
4.1.4.87 - SOLO-4092
| Code | SOLO-4092 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a mirror node is asked to import from a block node but block node integration does not apply to it. solo only configures a mirror node to read from a block node when a block node is registered in the same cluster, TSS is enabled and the consensus node version supports it; otherwise it would silently fall back to the consensus node’s record files, which is not what an explicit block node source asks for.
Troubleshooting Steps
- Deploy a block node in the same cluster first: solo block node add
- Check that TSS is enabled and that the consensus node version supports block node integration
- Use –force to bypass the version requirements
- Or use –mirror-node-source bucket|auto to import from the consensus node record files instead
4.1.4.88 - SOLO-4093
| Code | SOLO-4093 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when an admin public key provided via –admin-public-keys is not a valid DER-encoded ED25519 public key; the message reports the node alias. solo only supports ED25519 admin keys, so ECDSA or malformed inputs are rejected.
Troubleshooting Steps
- Provide a valid DER-encoded ED25519 public key in hexadecimal format for each consensus node
- Note that ECDSA keys are not supported for node admin keys
- Run solo consensus node setup –help for usage information
4.1.4.89 - SOLO-4094
| Code | SOLO-4094 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a configuration value set in an environment variable or a Solo config file cannot be read as the type its field declares, such as abc for a number or maybe for a boolean flag.
Troubleshooting Steps
- A boolean accepts true, false, 1 or 0, in any case; a number accepts an integer or decimal literal
- Correct or remove that value to fall back to the configured default
4.1.4.90 - SOLO-4095
| Code | SOLO-4095 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when the relayNode section of a one-shot values file sets a –chain-id that differs from the chain ID of the consensus node. EVM tooling such as Hardhat rejects a relay whose chain ID does not match the network.
Troubleshooting Steps
- Remove –chain-id from the relayNode section of the values file so the relay uses the consensus node chain ID
- Or set the same –chain-id in the network and relayNode sections of the values file
- Without –chain-id in the network section, the consensus node uses SOLO_CHAIN_ID, or 298 when it is unset
4.1.4.91 - SOLO-4096
| Code | SOLO-4096 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when consensus node add is run against a deployment that has no consensus nodes. Adding a node requires an existing network to submit the node create transaction to, so the first nodes must be deployed with consensus network deploy.
Troubleshooting Steps
- Nodes are declared at cluster attach, so create a new deployment (new namespace) with at least one node:
- solo deployment cluster attach –num-consensus-nodes
- then solo keys consensus generate, consensus network deploy, consensus node setup, consensus node start
- Use consensus node add only after the network is running.
4.1.4.92 - SOLO-4097
| Code | SOLO-4097 |
| Category | Validation |
| Ownership | User |
| Retryable | No |
Description
Thrown when a mirror node in a cluster without consensus nodes would import from the bucket. Such a cluster has no storage credentials, so the importer could only fail later, at download time. It needs a block node in the same cluster as its source.
Troubleshooting Steps
- Deploy a block node in the same cluster first: solo block node add
- Then use –mirror-node-source block-node
- Or deploy the mirror node in a cluster that has consensus nodes
4.1.4.93 - SOLO-5090
| Code | SOLO-5090 |
| Category | Validation |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when the PodLogs CRD YAML fetched for the pinned Grafana Alloy version does not describe the expected podlogs.monitoring.grafana.com CustomResourceDefinition. The message names the source URL and the mismatch. The response reached solo but is not the pinned upstream manifest — usually a network intermediary returning an error page or an unrelated file, occasionally an upstream repository move.
Troubleshooting Steps
- Re-run the command; a transient upstream response usually clears on retry
- Confirm that the pinned Grafana Alloy version still ships this CRD at grafana/alloy
- If the failure keeps recurring, file an issue against grafana/alloy at the pinned version
4.1.5 - System
4.1.5.1 - SOLO-2032
| Code | SOLO-2032 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when the MinIO Operator’s cluster-scoped CRDs exist but no Helm release owns them. The CRDs outlive the namespace the operator was installed into, so deleting that namespace leaves them behind. Helm will not adopt resources another release created, so installing over them fails; and treating their presence as “already installed” would be worse — the operator would never run, and the Tenant resource created later would sit unreconciled with nothing pointing at the cause.
Troubleshooting Steps
- Delete the leftover CRDs, then run the setup again: kubectl delete crd <crdNames.join(’ ‘)>
- Deleting these CRDs also deletes any MinIO Tenant resources defined by them
- They are usually left behind when the operator namespace was deleted directly rather than through solo cluster-ref config reset
4.1.5.2 - SOLO-5001
| Code | SOLO-5001 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when an expected resource cannot be found; the message names the resource and, when available, wraps the underlying cause. solo looks up Kubernetes and related resources by name as it works, so this means the resource was absent where it was expected — for example it was not yet created, was deleted, or was searched for in the wrong place.
Troubleshooting Steps
- Make sure the requested resource exists and is reachable, if not file a bug report: https://github.com/hiero-ledger/solo/issues
4.1.5.3 - SOLO-5002
| Code | SOLO-5002 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot establish a connection to the Kubernetes API server for a cluster reference; the message names the cluster reference and the kubeconfig context it tried. solo resolves the context from kubeconfig and connects before running any cluster operation, so this fires when that handshake fails: the context names a server that is unreachable or no longer exists, the cluster has not been started yet (for example a Kind cluster that was never created or was deleted), credentials have expired, or a transient network/DNS problem interrupted the call. It is retryable because a cluster that is still coming up, or a brief network blip, often resolves on a later attempt.
Troubleshooting Steps
- Verify the kubeconfig context is correct and the cluster is reachable: kubectl cluster-info –context
4.1.5.4 - SOLO-5003
| Code | SOLO-5003 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot refresh its port-forwards; when available the underlying failure is wrapped in cause. solo periodically re-establishes port-forwards so endpoints stay reachable, so this means that refresh failed — for example a target pod was unavailable or the API connection dropped. It is retryable.
Troubleshooting Steps
- Check the all pods exist and are running: kubectl get pods -n
- Check the port-forwards of your deployment: solo deployment config ports –deployment
- Restart the port-forward: solo deployment port-forwards refresh –deployment
4.1.5.5 - SOLO-5004
| Code | SOLO-5004 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot display port-forward status; when available the underlying failure is wrapped in cause. solo reads the state of active port-forwards to report it, so this means that status query failed — for example the cluster API was unreachable. It is retryable.
Troubleshooting Steps
- Check the all pods exist and are running: kubectl get pods -n
- Restart the port-forward: solo deployment port-forwards refresh –deployment
4.1.5.6 - SOLO-5005
| Code | SOLO-5005 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a referenced Kubernetes namespace does not exist; the message names the namespace. solo operates within a deployment namespace, so this means the namespace is absent — for example it was never created, was deleted, or the wrong name was supplied.
Troubleshooting Steps
- List existing namespaces: kubectl get namespaces
- Check the active deployment: solo deployment config info –deployment
- Redeploy the network to re-create the namespace: solo consensus network deploy
4.1.5.7 - SOLO-5006
| Code | SOLO-5006 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo queries Kubernetes for the pod backing a consensus node alias and the lookup returns no pod; the message names the alias. solo needs the pod to run commands, copy files, or check status on a node, so this fires when no pod matches the expected labels in the namespace. Because pod scheduling is asynchronous, it can appear briefly during startup before the pod exists, which is why it is retryable; if it persists, the pod failed to schedule or start, was evicted, or the node was never deployed. This is the base error for the component-specific variants (explorer, relay, mirror-node, block-node, and Postgres pod-not-found errors).
Troubleshooting Steps
- Check pod status: kubectl get pods -n
-l solo.hedera.com/node-name= - Describe the pod for events: kubectl describe pod -n
-l solo.hedera.com/node-name= - A StatefulSet whose claim cannot be provisioned never creates its pod; check PVC/PV binding: kubectl get pvc,pv -n
- Check the storage class and its provisioner: kubectl get storageclass
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.8 - SOLO-5007
| Code | SOLO-5007 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot find any HAProxy pods. solo relies on HAProxy pods to route traffic to consensus nodes, so this is raised when none are present in the namespace. It is retryable because the pods may still be scheduling; if it persists, HAProxy failed to start or was not deployed.
Troubleshooting Steps
- Check HAProxy pod status: kubectl get pods -n
-l solo.hedera.com/type=haproxy - Check the active deployment: solo deployment config info –deployment
- Redeploy the network if HAProxy is missing: solo consensus network deploy
4.1.5.9 - SOLO-5008
| Code | SOLO-5008 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot find the expected load balancer. solo looks up the load balancer that exposes a service externally, so this is raised when none is present yet. It is retryable because the load balancer may still be provisioning (for example waiting on MetalLB or a cloud provider); a persistent failure points to a networking misconfiguration.
Troubleshooting Steps
- Check load balancer service status: kubectl get svc -n
- Ensure your cloud provider supports LoadBalancer services
- Review cloud provisioning logs for LB assignment delays
4.1.5.10 - SOLO-5009
| Code | SOLO-5009 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo cannot determine the Kubernetes context for a node; the message names the node alias. By this point the node context should already be resolvable from configuration, so reaching it indicates an internal inconsistency and is treated as an internal Solo error.
Troubleshooting Steps
- Check active deployments: solo deployment config info
- Verify that the node alias is registered: kubectl get configmap -n
-o yaml - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.11 - SOLO-5010
| Code | SOLO-5010 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo looks up a consensus node by alias but it is not present in the configuration; the message names the alias. By this point the node should already be known, so reaching it indicates an internal inconsistency between the requested alias and the loaded configuration, and is treated as an internal Solo error.
Troubleshooting Steps
- List registered nodes: solo deployment config info –deployment
- Verify the node alias: kubectl get configmap -n
-o yaml | grep nodeAlias - Re-run with a valid alias: solo node
–node-aliases
4.1.5.12 - SOLO-5011
| Code | SOLO-5011 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot create a Kubernetes secret; the message describes the secret and, when available, wraps the underlying cause. solo stores keys and credentials as cluster secrets, so this means the secret could not be created — for example the namespace is missing, the API rejected the request, or a transient API error occurred. It is retryable.
Troubleshooting Steps
- Check RBAC permissions: kubectl auth can-i create secrets -n
- Inspect existing secrets: kubectl get secrets -n
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the cluster is reachable: kubectl cluster-info –context
4.1.5.13 - SOLO-5012
| Code | SOLO-5012 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when the states directory for a node does not exist; the message names the node alias and the expected directory. solo reads saved consensus state from this directory, so this means it is missing or the path is wrong — for example no state was exported for the node, or the wrong path was supplied.
Troubleshooting Steps
- Verify the states directory exists: ls -la
- Check that the state download succeeded: solo consensus node states
- Use the correct –inputDir path structure:
/states/ / /
4.1.5.14 - SOLO-5013
| Code | SOLO-5013 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a configured port-forward is not present; the message names the component, its id, and the local-to-pod port mapping. solo expects each configured port-forward to be active so the component is reachable, so this means it is missing — for example it was never established or was dropped. It is retryable, since re-establishing the port-forward often succeeds.
Troubleshooting Steps
- Check port-forward status: solo deployment diagnostics connections –deployment
- Re-establish port forwards: solo consensus node start
- Verify the pod is running: kubectl get pods -n
4.1.5.15 - SOLO-5014
| Code | SOLO-5014 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when no PersistentVolumeClaims are found in a namespace where they were expected; the message names the namespace. Some operations require PVCs that are created only when persistent storage is enabled at deployment, so this means PVCs were not enabled for the network — redeploy with PVCs enabled.
Troubleshooting Steps
- Redeploy with PVCs enabled: solo consensus network deploy –pvcs true
4.1.5.16 - SOLO-5015
| Code | SOLO-5015 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown during initialization when solo cannot determine which cluster reference to use. solo expects the active cluster reference to be resolvable at this point, so reaching this indicates an internal initialization or ordering defect rather than user input, and is treated as an internal Solo error.
Troubleshooting Steps
- Check the remote config: kubectl get configmap -n
-o yaml - Verify cluster references: solo deployment config info –deployment
- Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.17 - SOLO-5016
| Code | SOLO-5016 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot fetch a requested upgrade version; the message names the version and wraps the underlying failure in cause. solo downloads upgrade artifacts for the chosen version, so this means the fetch did not complete — for example the version assets were unreachable or the download errored. It is retryable, since transient network issues often clear on a later attempt.
Troubleshooting Steps
- Check internet connectivity
- Verify the version exists: https://github.com/hashgraph/hedera-services/releases
- Retry the upgrade: solo consensus network upgrade –upgrade-version
4.1.5.18 - SOLO-5017
| Code | SOLO-5017 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a command needs a single deployment but several are configured and none was selected; the message names the source (local or remote) and the deployments found. solo cannot guess which one to use, so it asks you to disambiguate with --deployment.
Troubleshooting Steps
- List existing deployments: solo deployment config list
- Specify the deployment explicitly: solo node
–deployment
4.1.5.19 - SOLO-5018
| Code | SOLO-5018 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot set the gRPC Web proxy endpoint. solo configures this endpoint so gRPC Web clients can reach the network, so this means that configuration step failed — for example the target service or port-forward was not reachable. It is retryable, since a transient connectivity issue often clears on a later attempt.
Troubleshooting Steps
- Check node update transaction logs: tail -n 100 ~/.solo/logs/solo.log
- Verify gRPC endpoints are reachable: kubectl get svc -n
- Retry the node update: solo consensus node update
4.1.5.20 - SOLO-5019
| Code | SOLO-5019 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot find a Hiero Explorer pod. solo locates the explorer pod to operate on it or check its status, so this is raised when no matching pod exists in the namespace — for example the explorer failed to start, was removed, or was never deployed.
Troubleshooting Steps
- Check pod status: kubectl get pods -A | grep explorer
- Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/component=hiero-explorer
- Check recent namespace events: kubectl get events -n
–sort-by=.lastTimestamp
4.1.5.21 - SOLO-5020
| Code | SOLO-5020 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when no Hiero Explorer component is present in the deployment remote configuration. solo looks the explorer up in the remote config before acting on it, so this means none is recorded — typically because the explorer was never deployed for this deployment, or was already removed.
Troubleshooting Steps
- List components in remote config: solo deployment config info
- Deploy the explorer first: solo explorer deploy
4.1.5.22 - SOLO-5021
| Code | SOLO-5021 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot find a JSON-RPC relay pod. solo locates the relay pod to operate on it or check status, so this is raised when no matching pod exists in the namespace — for example the relay failed to start, was removed, or was never deployed.
Troubleshooting Steps
- Check pod status: kubectl get pods -A | grep relay
- Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/instance=relay-
- Check recent namespace events: kubectl get events -n
–sort-by=.lastTimestamp
4.1.5.23 - SOLO-5022
| Code | SOLO-5022 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when no JSON-RPC relay is present in the deployment remote configuration. solo looks the relay up in the remote config before acting on it, so this means none is recorded — typically because it was never deployed for this deployment, or was already removed.
Troubleshooting Steps
- List components in remote config: solo deployment config info
- Deploy the relay first: solo relay deploy
4.1.5.24 - SOLO-5023
| Code | SOLO-5023 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot find any deployed mirror-node pods; the message names the release and namespace. solo locates the mirror node pods to operate on them, so this is raised when none match in the namespace — for example the release failed to deploy, was removed, or the wrong release or namespace was targeted.
Troubleshooting Steps
- Check pod status: kubectl get pods -n
| grep - Inspect Helm release: helm status
-n
4.1.5.25 - SOLO-5024
| Code | SOLO-5024 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot find the mirror ingress controller pod. solo locates this pod to manage ingress for the mirror node, so this is raised when no matching pod exists in the namespace — for example it failed to start or was not deployed.
Troubleshooting Steps
- Check ingress controller pod status: kubectl get pods -A | grep ingress
- Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/name=haproxy-ingress
- Check recent namespace events: kubectl get events -n
–sort-by=.lastTimestamp
4.1.5.26 - SOLO-5025
| Code | SOLO-5025 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when no mirror node is present in the deployment remote configuration. solo looks the mirror node up in the remote config before acting on it, so this means none is recorded — typically because it was never deployed for this deployment, or was already removed.
Troubleshooting Steps
- List components in remote config: solo deployment config info
- Deploy the mirror node first: solo mirror node add –deployment
4.1.5.27 - SOLO-5026
| Code | SOLO-5026 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a referenced cluster is not present in the deployment remote configuration; the message names the cluster reference. solo expects the cluster to be recorded in the remote config before acting on it, so this means the reference does not match any recorded cluster — typically a misspelled name or a cluster that was never attached to the deployment.
Troubleshooting Steps
- List configured cluster references: solo cluster-ref list
- Inspect the remote config to see which clusters block nodes reference: kubectl get configmap solo-remote-config -n
-o yaml - If the cluster was renamed or removed, the deployment config may need to be repaired
4.1.5.28 - SOLO-5027
| Code | SOLO-5027 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a GitHub API request cannot be completed; the message names the URL and wraps the underlying failure in cause. The request did not produce a usable HTTP response at all — for example a network or DNS failure, or a dropped connection. It is retryable, since transient network problems often clear on a later attempt.
Troubleshooting Steps
- Check network connectivity and GitHub availability, then retry. If the issue persists, confirm proxy/firewall settings.
4.1.5.29 - SOLO-5028
| Code | SOLO-5028 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a GitHub API request returns a non-success HTTP status; the message names the URL and the status code. solo calls the GitHub API to discover releases and download assets, so this means GitHub responded with an error status — for example rate limiting, a missing resource, or a server error. It is retryable, since transient statuses such as rate limits often clear on a later attempt.
Troubleshooting Steps
- Verify GitHub API accessibility and credentials/rate limits, then retry.
4.1.5.30 - SOLO-5029
| Code | SOLO-5029 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot parse a GitHub API response; the message names the URL and wraps the underlying failure in cause. solo parses release metadata from the API, so this means the body could not be parsed — for example it was not valid JSON or did not match the expected structure.
Troubleshooting Steps
- Inspect the GitHub API response shape and endpoint contract.
4.1.5.31 - SOLO-5030
| Code | SOLO-5030 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a GitHub API response is missing the expected tag_name field; the message names the URL. solo reads tag_name to identify a release version, so this means the response came back without it — indicating an unexpected response shape from the API.
Troubleshooting Steps
- Confirm the repository has a latest release and that the GitHub API response contains expected release fields.
4.1.5.32 - SOLO-5031
| Code | SOLO-5031 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot find a running block node pod. solo locates the block node pod to run commands or check its status, so this is raised when no matching pod exists in the namespace. It is retryable because pod scheduling is asynchronous and the pod may appear shortly; if it persists, the block node failed to start or was never deployed.
Troubleshooting Steps
- Check pod status: kubectl get pods -A -l block-node.hiero.com/type=block-node
- Describe pods to check for crashes or evictions: kubectl describe pods -A -l block-node.hiero.com/type=block-node
- Check recent namespace events: kubectl get events -n
–sort-by=.lastTimestamp
4.1.5.33 - SOLO-5032
| Code | SOLO-5032 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a deployed block node does not become ready; the message names the release and wraps the underlying failure in cause. solo waits for the block node pods to reach a Ready state, so this means that wait did not succeed. It is retryable, since a block node that is merely slow to start often becomes ready on a later attempt; a persistent failure points to a crash-looping or misconfigured block node.
Troubleshooting Steps
- Check block node pod status: kubectl get pods -A | grep
- Describe pods for readiness probe failures: kubectl describe pods -A -l app.kubernetes.io/instance=
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.34 - SOLO-5033
| Code | SOLO-5033 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a referenced block node is not present in the deployment remote configuration; when provided, the message includes its identifier. solo looks components up in the remote config before acting on them, so this means the block node id does not match any recorded component — typically because it was never added, was already removed, or the wrong id was supplied.
Troubleshooting Steps
- List all registered components: solo deployment config info
- Verify you are targeting the correct deployment and namespace
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.35 - SOLO-5034
| Code | SOLO-5034 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a referenced external block node is not present in the deployment remote configuration; when provided, the message includes its id. solo looks external block nodes up in the remote config before acting on them, so this means the id does not match any recorded external block node — typically because it was never added or the wrong id was supplied.
Troubleshooting Steps
- Register the external block node first: solo block node add-external
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.36 - SOLO-5035
| Code | SOLO-5035 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot set up the Helm chart repositories; the underlying failure is wrapped in cause. solo adds and updates the repositories its charts come from, so this means that setup failed — for example a repository URL was unreachable or the Helm CLI errored.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List configured Helm repositories: helm repo list
- Verify network connectivity to chart repository URLs
- Remove a stale repository entry: helm repo remove
- Re-run the command; solo re-adds the repositories it manages
4.1.5.37 - SOLO-5036
| Code | SOLO-5036 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot check the configured Helm chart repositories; the underlying failure is wrapped in cause. solo verifies repositories before installing charts from them, so this means that check failed — for example the Helm CLI errored or a repository was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- List configured Helm repositories: helm repo list
- Verify network connectivity to chart repository URLs
- Update Helm repositories: helm repo update
4.1.5.38 - SOLO-5037
| Code | SOLO-5037 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot list installed Helm charts; the underlying failure is wrapped in cause. solo lists releases to check what is installed, so this means the helm list failed — for example the Helm CLI errored or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl cluster-info
- List Helm releases manually: helm list -A
4.1.5.39 - SOLO-5038
| Code | SOLO-5038 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot install a Helm chart release; the message names the release and wraps the underlying failure in cause. This is the generic install failure used by the Helm client, so it means the helm install did not succeed — for example a bad chart version or values, an image that cannot be pulled, or a cluster that is unreachable or short on resources.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect the Helm release: helm status
-n - Check Helm release history: helm history
-n - Inspect failing pods: kubectl get pods -A
4.1.5.40 - SOLO-5039
| Code | SOLO-5039 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot uninstall a Helm chart release; the message names the release and wraps the underlying failure in cause. solo uninstalls releases during teardown, so this means the helm uninstall did not complete — for example the release was not found, a resource could not be deleted, or the cluster API was unreachable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Check if the release still exists: helm list -n
- Inspect the release status: helm status
-n - Check remaining pods: kubectl get pods -A
4.1.5.41 - SOLO-5040
| Code | SOLO-5040 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot upgrade a Helm chart release; the message names the release and wraps the underlying failure in cause. solo upgrades releases to change chart version or values, so this means the helm upgrade did not succeed — for example a bad chart or values, an image that cannot be pulled, or a cluster issue.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect the release status: helm status
-n - Review upgrade history: helm history
-n - Check failing pods: kubectl get pods -A
4.1.5.42 - SOLO-5041
| Code | SOLO-5041 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a file solo was asked to use does not exist; the message names the path. solo reads files from paths provided on the command line or in configuration, so this means the file is missing or the path is wrong — for example a typo or a file that was moved or deleted.
Troubleshooting Steps
- Verify the file exists at:
- Check the path is correct and the file has not been deleted
4.1.5.43 - SOLO-5042
| Code | SOLO-5042 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a file copy operation fails; the underlying failure is wrapped in cause. solo copies files between local paths and pods during setup, so this means the copy did not complete — for example the source was unreadable, the destination was not writable, or the connection dropped.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the source file exists and is readable
- Check that the destination directory exists and is writable
- Verify sufficient disk space is available
4.1.5.44 - SOLO-5043
| Code | SOLO-5043 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a file solo was asked to read is empty; the message names the path. solo expects the referenced file to contain data, so this means it exists but has no content — for example the wrong file was supplied or it was not fully written.
Troubleshooting Steps
- Verify the file contains valid content:
- The file must not be empty to be processed
4.1.5.45 - SOLO-5044
| Code | SOLO-5044 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a file solo was asked to parse does not contain valid JSON; the message names the path. solo parses JSON from user-provided files, so this means the content could not be parsed — for example a syntax error, a truncated file, or a non-JSON file supplied.
Troubleshooting Steps
- Verify the file at
contains valid JSON - Check for syntax errors such as missing commas, brackets, or quotes
4.1.5.46 - SOLO-5045
| Code | SOLO-5045 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create a directory; the underlying failure is wrapped in cause. solo creates working and output directories as it runs, so this means the directory could not be created — for example missing permissions, a read-only or full disk, or a conflicting existing path.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the parent directory exists and is writable
- Check available disk space
4.1.5.47 - SOLO-5046
| Code | SOLO-5046 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot unzip an archive; the message names the source and wraps the underlying failure in cause. solo unzips downloaded packages and state archives, so this means the unzip failed — for example the zip is corrupt or truncated, a wrong password was supplied, or the destination could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the archive is a valid zip file:
- Ensure the archive is not corrupted
- Check available disk space in the destination
4.1.5.48 - SOLO-5047
| Code | SOLO-5047 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create a tar archive from a source path; the message names the source and wraps the underlying failure in cause. solo packages directories into tar archives (for example to bundle state or logs), so this means the archiving step failed — for example the source path was unreadable, a file changed during archiving, or the destination could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the source path exists and is readable:
- Check available disk space for the output archive
4.1.5.49 - SOLO-5048
| Code | SOLO-5048 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot extract a tar archive; the message names the archive and wraps the underlying failure in cause. solo unpacks tar archives it downloads or restores, so this means extraction failed — for example the archive is corrupt or truncated, or the destination directory could not be written.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the archive is a valid tar file:
- Check the archive is not corrupted
- Verify available disk space in the extraction destination
4.1.5.50 - SOLO-5049
| Code | SOLO-5049 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot determine the installed version of a dependency; the message names the dependency and, when present, wraps the underlying cause (otherwise it notes the tool may not be installed or on PATH). solo checks tool versions to confirm they meet its requirements, so this means the version check could not run or its output could not be parsed.
Troubleshooting Steps
- Verify
is installed and available in your PATH - Check the installation: which
- Re-run the command; solo installs the dependencies it manages automatically
4.1.5.51 - SOLO-5050
| Code | SOLO-5050 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a required dependency is not found; the message names it. solo expects certain external tools to be available, so this means the dependency could not be located — for example it is not installed or not on PATH.
Troubleshooting Steps
- Install the missing dependency:
- Re-run the command; solo installs the dependencies it manages automatically
- Verify the dependency is in your PATH: which
4.1.5.52 - SOLO-5051
| Code | SOLO-5051 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when no dependency manager is registered for a requested dependency; the message names the dependency. solo routes each managed dependency to a registered manager that knows how to install and verify it, so a missing registration points to an internal wiring defect and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.5.53 - SOLO-5052
| Code | SOLO-5052 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot install a managed dependency; the message names the executable and wraps the underlying failure in cause. solo installs tools like kubectl, helm, and kind when they are missing, so this means installation failed — for example the download failed, the archive was invalid, or the target directory was not writable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify network connectivity for downloading the dependency
- Check available disk space
- Re-run the command to retry the installation
4.1.5.54 - SOLO-5053
| Code | SOLO-5053 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when the chosen installation directory is the same as the temporary directory used during install. solo installs managed dependencies (such as kubectl, helm, kind) into a target directory distinct from its temp workspace, so this means the configured paths collide — choose a different installation directory.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Configure separate installation and temporary directories in your Solo configuration
4.1.5.55 - SOLO-5054
| Code | SOLO-5054 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a GitHub repository reports no releases. solo lists releases to choose a version to download, so this means the repository returned an empty release list. It is retryable, since a transient API issue can return empty results that resolve on a later attempt.
Troubleshooting Steps
- Verify network connectivity and GitHub availability
- Check if GitHub API rate limits have been exceeded
- Verify proxy or firewall settings allow access to api.github.com
4.1.5.56 - SOLO-5055
| Code | SOLO-5055 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when no GitHub release exists for a requested tag; the message names the tag. solo looks up releases by tag to download a specific version, so this means that tag has no release — for example a wrong or not-yet-published version.
Troubleshooting Steps
- Verify the release tag ‘
’ exists in the GitHub repository - Check the GitHub releases page for available versions
- Verify network connectivity to api.github.com
4.1.5.57 - SOLO-5056
| Code | SOLO-5056 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when no GitHub release asset matches the running platform and architecture; the message names the platform and arch. solo selects the release asset built for the current OS and CPU, so this means the release exists but has no matching asset — for example the platform or architecture is unsupported by that release.
Troubleshooting Steps
- Verify a release asset is available for your platform (
) and architecture ( ) - Check the GitHub releases page for supported platforms
- Consider installing the dependency manually
4.1.5.58 - SOLO-5057
| Code | SOLO-5057 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot install Homebrew. On macOS solo may use Homebrew to install some dependencies, so this means the Homebrew installation did not succeed — for example the install script failed or could not be downloaded.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify network connectivity
- Install Homebrew manually from https://brew.sh
- Re-run the command after installing Homebrew
4.1.5.59 - SOLO-5058
| Code | SOLO-5058 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot inspect the Podman machine; the underlying failure is wrapped in cause. When using Podman, solo inspects the machine to read its configuration, so this means that inspection failed — for example Podman is not installed, the machine is not running, or the command errored.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Podman is installed: podman –version
- List Podman machines: podman machine list
- Start the Podman machine if it is not running: podman machine start
4.1.5.60 - SOLO-5059
| Code | SOLO-5059 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when solo detects stale Docker authentication for the GitHub Container Registry (GHCR). solo needs valid GHCR credentials to pull images, so this means the cached Docker auth is expired or invalid — re-authenticate to GHCR to refresh it.
Troubleshooting Steps
- Re-authenticate with the GitHub Container Registry: docker login ghcr.io
- Verify your GitHub Personal Access Token has the read:packages scope
- Clear stale credentials: docker logout ghcr.io
4.1.5.61 - SOLO-5060
| Code | SOLO-5060 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create a PersistentVolumeClaim. solo provisions PVCs for components that need persistent storage, so this means the create request failed — for example the API rejected the spec, or no StorageClass could satisfy it.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify available storage in the cluster: kubectl get pv
- Check if a StorageClass is configured: kubectl get storageclass
- Inspect PVC events: kubectl describe pvc -n
4.1.5.62 - SOLO-5061
| Code | SOLO-5061 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the Kubernetes API returns an incorrect or unexpected response; when the underlying failure is known it is named in the message and wrapped in cause. solo expects well-formed responses from the API, so this means a call returned something it could not interpret — for example a malformed or partial response, often indicating an API server problem.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes API server is reachable: kubectl cluster-info
- Check kubeconfig context: kubectl config current-context
- Inspect Kubernetes API server health
4.1.5.63 - SOLO-5062
| Code | SOLO-5062 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot list Kubernetes IngressClasses; the underlying failure is wrapped in cause. solo reads IngressClasses to configure ingress for components, so this means the lookup failed — for example the cluster API was unreachable or the current user lacks permission.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Kubernetes connectivity: kubectl cluster-info
- List IngressClasses manually: kubectl get ingressclass
- Ensure the Kubernetes API server supports IngressClass resources (requires v1.18+)
4.1.5.64 - SOLO-5063
| Code | SOLO-5063 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a Kubernetes lookup that expected a single resource matches more than one; the filters used are attached to the error. solo expects these filtered lookups to be unique, so multiple matches indicate an internal assumption was violated (for example over-broad filters), and it is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.5.65 - SOLO-5064
| Code | SOLO-5064 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot create a Kubernetes pod. solo creates helper or workload pods as part of its operations, so this means the create request did not yield a running pod — for example the API rejected the spec, scheduling failed, or required resources were unavailable.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Inspect pod events: kubectl get events -n
- Check resource quotas: kubectl describe namespace
- Verify node resource availability: kubectl get nodes
4.1.5.66 - SOLO-5065
| Code | SOLO-5065 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot download a package; the message names the URL and wraps the underlying failure in cause. solo downloads packages such as platform builds and tools, so this means the download did not complete — for example the URL was unreachable, returned an error, or the connection dropped. It is retryable, since transient network issues often clear on a later attempt.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify network connectivity
- Check if proxy or firewall settings block access to the download URL
- Verify the download URL is accessible
4.1.5.67 - SOLO-5066
| Code | SOLO-5066 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot read a checksum file; the message names the file. solo reads checksum files to verify downloaded artifacts, so this means the file could not be read — for example it is missing, empty, or unreadable due to permissions or an interrupted download.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the checksum file exists and is readable:
- Re-download the package to regenerate the checksum file
4.1.5.68 - SOLO-5067
| Code | SOLO-5067 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo is given an invalid path for a container operation; the message names the context and the path. solo validates container paths before using them for copy or exec operations, so an invalid value here (for example an empty or malformed path passed internally) points to a defect in the calling code and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.5.69 - SOLO-5068
| Code | SOLO-5068 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when an operation against a container fails; the message names the operation and wraps the underlying failure in cause. solo runs operations such as exec and file copy inside pod containers, so this means that operation failed — for example the container was not reachable, the command errored, or the connection dropped.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the pod is running: kubectl get pods -n
- Inspect pod logs: kubectl logs
-n - Check pod status: kubectl describe pod
-n
4.1.5.70 - SOLO-5069
| Code | SOLO-5069 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot find the Postgres pod; the message names the namespace. solo locates the mirror node Postgres pod to operate on the database, so this is raised when no matching pod exists in the namespace — for example the database failed to start or was not deployed.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify Postgres pods are running: kubectl get pods -n
-l app.kubernetes.io/name=postgresql - Inspect Postgres deployment: kubectl describe deployment -n
- Re-deploy the mirror node to recreate Postgres: solo mirror node add
4.1.5.71 - SOLO-5070
| Code | SOLO-5070 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot initialize its system files; the underlying failure is wrapped in cause. solo lays down the files it needs under its home directory during initialization, so this means that step failed — for example the directory was not writable or a file could not be created.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify write permissions for the Solo home directory (~/.solo)
- Check available disk space
- Re-run the command; solo sets up its system files at the start of every command
4.1.5.72 - SOLO-5071
| Code | SOLO-5071 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a cache is built before its required provider or engine has been set; the message names the cache and which piece is missing. solo requires both to be configured before constructing the cache, so reaching this points to an internal setup or ordering defect rather than user input, and is treated as an internal Solo error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.5.73 - SOLO-5072
| Code | SOLO-5072 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when pods do not terminate within the allotted time; the message names the namespace and the label selector being waited on. solo waits for matching pods to disappear during teardown, so this means they were still present when the deadline passed — for example a pod is stuck terminating or has a finalizer. It is retryable, since termination often completes shortly after.
Troubleshooting Steps
- List pods still present: kubectl get pods -n
-l <labels.join(’,’)> - Describe stuck pods for termination events: kubectl describe pod -n
-l <labels.join(’,’)> - Check for finalizers blocking deletion: kubectl get pod -n
-l <labels.join(’,’)> -o jsonpath=’{.items[*].metadata.finalizers}' - Force-delete stuck pods if safe: kubectl delete pod -n
-l <labels.join(’,’)> –force –grace-period=0 - Check solo logs for context: tail -n 100 ~/.solo/logs/solo.log
4.1.5.74 - SOLO-5073
| Code | SOLO-5073 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot check whether a Kubernetes ClusterRole exists; the message names the role and wraps the underlying failure in cause. solo queries for ClusterRoles before installing or relying on them, so this means the lookup failed — for example the Kubernetes API was unreachable or the current user lacks permission to read ClusterRoles.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify RBAC permissions: kubectl get clusterroles
- Inspect cluster state: kubectl get pods -A
4.1.5.75 - SOLO-5074
| Code | SOLO-5074 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when Solo cannot determine a supported native package manager for the current Linux distribution, so it cannot automatically install system dependencies (git, iptables, podman). Solo supports apt-get (Debian/Ubuntu), dnf (Fedora/RHEL), yum (RHEL 7/CentOS 7), zypper (openSUSE), pacman (Arch) and apk (Alpine).
Troubleshooting Steps
- Install one of the supported package managers (apt-get, dnf, yum, zypper, pacman, apk), or
- Install Solo and its dependencies (podman, git, iptables) manually, then re-run the command
4.1.5.76 - SOLO-5075
| Code | SOLO-5075 |
| Category | System |
| Ownership | User |
| Retryable | No |
Troubleshooting Steps
- Ensure at least one block node is deployed: solo block-node deploy
- Check the block node mapping flags: –block-node-mapping or –external-block-node-mapping
- List all registered components: solo deployment config info
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.77 - SOLO-5076
| Code | SOLO-5076 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when helm pull completes without error but no new chart tarball appears in the cache charts directory; the message names the chart and version that were being cached. solo identifies the pulled archive by diffing the directory contents before and after the pull, so an empty diff means Helm reported success without producing the expected .tgz — for example due to an unexpected Helm CLI behaviour change or a filesystem issue in the cache directory.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the Helm CLI works: helm version
- Try pulling the chart manually: helm pull
–version
4.1.5.78 - SOLO-5077
| Code | SOLO-5077 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the container runtime stack behind the Homebrew-installed podman on Linux cannot be configured or fails its post-configuration probe — for example the crun or conmon binary is missing from the Homebrew prefix, a network helper download failed, or podman rejects the generated configuration. Without this configuration podman would fall back to the host’s system container stack, which may be too old for it.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the Homebrew podman installation: brew doctor && podman info
- Inspect the generated configuration files under ~/.solo/config (containers.conf, registries.conf)
- Reinstall the Homebrew podman stack if binaries are missing: brew reinstall podman
4.1.5.79 - SOLO-5078
| Code | SOLO-5078 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a Kubernetes API call against a remote cluster fails for any reason other than the resource being absent; the message names the kubeconfig context and the underlying failure, which is also wrapped in cause. solo reads and writes cluster state over the Kubernetes API for every deployment operation, so this means the call never produced a usable answer: the API server is down or unreachable over the network, the kubeconfig context points at a cluster that no longer exists, credentials have expired, or RBAC denied the request. Kind clusters are excluded — a local kind API failure is reported as a Kubernetes API invalid response instead. It is retryable because an API server that is restarting, or a transient network problem, often clears on a later attempt.
Troubleshooting Steps
- Verify the cluster is reachable: kubectl cluster-info –context
- Verify the kubeconfig context still exists: kubectl config get-contexts
- Verify your credentials and RBAC permissions for the namespace
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.80 - SOLO-5079
| Code | SOLO-5079 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a kind cluster’s node container was found stopped, solo started it again, and the cluster’s Kubernetes API still did not answer; the last API failure is wrapped in cause. A kind node that restarts but never serves its API usually means the cluster did not survive whatever stopped it — the host was rebooted and the node’s networking or storage no longer lines up, the container is crash-looping, or the kubeconfig entry now points at a port the restarted node no longer listens on. It is retryable because a control plane can simply need longer than solo waited.
Troubleshooting Steps
- Check the node container is running: docker ps -a –filter name=
-control-plane - Inspect why the node is not serving its API: docker logs
-control-plane - Verify the cluster answers: kubectl cluster-info –context kind-
- Recreate the cluster if it did not survive being stopped: kind delete cluster –name
4.1.5.81 - SOLO-5080
| Code | SOLO-5080 |
| Category | System |
| Ownership | User |
| Retryable | Yes |
Description
Thrown when solo needs the local container engine and neither Docker nor Podman answers; the failure that led solo to look is wrapped in cause. A local kind cluster only exists as containers on this machine, so with no engine running solo can neither reach the cluster nor tell whether it is still there. The usual reason is simply that Docker Desktop, the Docker daemon or the Podman machine is not started. solo does not start the engine itself, because doing so is platform-specific and needs privileges the CLI should not take on its own. It is retryable once the engine is up.
Troubleshooting Steps
- Start Docker Desktop, or the Docker daemon: sudo systemctl start docker
- If you use Podman, start its machine: podman machine start
- Confirm the engine answers: docker info
- Then re-run the command
4.1.5.82 - SOLO-5081
| Code | SOLO-5081 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a pod matching the expected labels was found but never reached the required phase or readiness condition before solo stopped waiting; the message names the pod, its last observed phase, and a per-container summary (readiness, restart count, and any waiting/terminated reason). This is distinct from the pod-not-found errors: the pod exists, but something is keeping it from becoming ready — most commonly a failing startup or readiness probe, a crash-looping container, or an unreachable dependency the container’s health check verifies. It is retryable because readiness is often only delayed; if it persists, inspect the pod rather than the scheduler.
Troubleshooting Steps
- Describe the pod for probe failures and events: kubectl describe pod -n
- Check container logs, including the previous run: kubectl logs -n
–previous - If the readiness probe checks a dependency (e.g. a mirror node or database), verify that dependency is healthy
- Check PVC/PV binding and volume attach events: kubectl get pvc -n
; kubectl describe pvc -n - Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.83 - SOLO-5082
| Code | SOLO-5082 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo cannot stop its port-forwards; when available the underlying failure is wrapped in cause. Stopping tears down the running kubectl port-forward processes and removes their configuration from the deployment’s remote config, so this means that teardown failed — for example a process could not be signalled or the remote config could not be persisted. It is retryable.
Troubleshooting Steps
- Check the port-forwards of your deployment: solo deployment config ports –deployment
- Check for lingering processes: ps aux | grep port-forward
4.1.5.84 - SOLO-5083
| Code | SOLO-5083 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when solo cannot write to its log directory or to one of the log files inside it; the message names the offending path and the underlying failure is wrapped in cause. solo opens solo.ndjson and solo.log under its logs directory before running any command, so an unwritable path there stops every invocation — including solo --version, which otherwise touches nothing. The usual cause is a directory or log file left behind by an installation that ran as a different user, for example an earlier sudo npm install -g @hiero-ledger/solo, which leaves the files owned by root.
Troubleshooting Steps
- Check who owns the path: ls -la ~/.solo ~/.solo/logs
- Take ownership if it belongs to another user: sudo chown -R “$(id -u):$(id -g)” ~/.solo
- Or delete the directory and let solo recreate it: rm -rf ~/.solo
- Reinstall without sudo so no root-owned files are left behind: npm install -g @hiero-ledger/solo
- Or point solo at a writable location instead: export SOLO_HOME=
4.1.5.85 - SOLO-5084
| Code | SOLO-5084 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when PVC mount verification finds that a pod’s PersistentVolumeClaim mounts are not backed by the storage the claims requested, and verification was configured to fail rather than warn. Provisioners that hand out directories on an existing filesystem do not enforce the requested size, so this condition is invisible to Kubernetes: the claim binds, the pod runs, and the shortfall only surfaces later as a full disk. The usual cause is that the directory tree the provisioner writes into is not the mount point it was meant to be — a data array that failed to mount at boot leaves the path on the system disk instead.
Troubleshooting Steps
- Check what the claims bound to and how large they really are: kubectl get pvc,pv -n
- Identify the provisioner and the host directory it writes into: kubectl get storageclass -o yaml
- On the node, confirm that directory is on the intended device and not the system disk: df -h
; lsblk; findmnt - If an intended data array or disk failed to mount at boot, mount it and redeploy so the claims are provisioned onto it
- To deploy anyway and only warn, omit –verify-pvc-mounts
4.1.5.86 - SOLO-5085
| Code | SOLO-5085 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when the consensus-node container has none of sha256sum, shasum, or openssl; the message names the pod. wait-for-stable-saved-state.sh fingerprints the saved-state directory with whichever of those is available to detect when background flushes stop changing disk contents, and this is permanent for a given image rather than something that resolves with more polling attempts, so solo fails fast instead of waiting out the full saved-state stability timeout.
Troubleshooting Steps
- Use a consensus-node image that includes sha256sum, shasum, or openssl
- Check the image in use: kubectl get pod
-n -o jsonpath="{.spec.containers[*].image}"
4.1.5.87 - SOLO-5086
| Code | SOLO-5086 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when the image cache manifest cannot be downloaded from the Solo release assets; the message names the manifest URL. solo reads this manifest to learn which image archives to download, so this means the release has no manifest published or the network call failed — check connectivity and confirm the running Solo version has a published release.
Troubleshooting Steps
- Confirm the machine can reach github.com
- Confirm the running Solo version has a published release with a cache-manifest.json asset
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.88 - SOLO-5087
| Code | SOLO-5087 |
| Category | System |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when the downloaded image cache manifest does not match the expected schema; the message names the manifest URL and what was wrong. solo refuses to act on a manifest it cannot fully validate because the entries drive downloads and hash checks, so this means the published artifact is malformed — report it.
Troubleshooting Steps
- File a bug report with the manifest URL: https://github.com/hiero-ledger/solo/issues
4.1.5.89 - SOLO-5088
| Code | SOLO-5088 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when a cached image archive no longer matches the SHA-256 published for it (in the image cache manifest or its cached .sha256 file), checked again immediately before the archive is loaded into the cluster; the message names the image and the archive. solo refuses to load bytes it cannot vouch for, so this means the archive was corrupted or altered after it was downloaded — the archive has been deleted and solo cache image pull will download it again.
Troubleshooting Steps
- Run
solo cache image pullto download the archive again, then retry - The archive has already been deleted, so the next pull will not skip it
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.90 - SOLO-5089
| Code | SOLO-5089 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when a file solo previously cached under SOLO_HOME can no longer be opened; the message names the path and the underlying failure is in cause. The cache is reused across deploys, so this means the file survived but its permissions no longer allow access — on Windows an empty DACL (which denies every principal, including the owner, and blocks deletion) and on POSIX a foreign owner or a cleared mode are the usual roots.
Troubleshooting Steps
- This is a local cache problem, not a cluster problem; the cluster does not need to be recreated
- On Windows, repair the permissions: icacls “
” /reset - If that reports access denied, take ownership first: takeown /f “
” - On macOS and Linux, check the owner and mode: ls -l
- Then delete the file so solo re-creates it on the next run
- To repair the whole cache on Windows: takeown /f “%USERPROFILE%.solo” /r /d y && icacls “%USERPROFILE%.solo” /reset /t /c /q
4.1.5.91 - SOLO-5091
| Code | SOLO-5091 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a block node does not expose any block above the mirror importer’s last imported block within the wait window; the message names the block number and the wait duration. It is retryable, since the block node may simply still be starting after a restore; a persistent failure points to a consensus node that is not streaming blocks to the block node.
Troubleshooting Steps
- Verify the consensus node is ACTIVE and streaming blocks to the block node
- Check block node logs for the status heartbeat (newestBlock): kubectl logs -A -l app.kubernetes.io/name=block-node
- Re-run: solo config ops bridge-import-gap
4.1.5.92 - SOLO-5092
| Code | SOLO-5092 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | No |
Description
Thrown when no image cache manifest has been published for the running Solo version; the message names the manifest URL. Solo reads this manifest to learn which image archives to download, so this means the release has no manifest published asset — an expected condition for releases or versions where the manifest has not been published.
Troubleshooting Steps
- Solo can run without an image cache; missing images will be pulled directly from their registries.
- To use a custom image cache manifest, set the SOLO_CACHE_MANIFEST_URL environment variable.
4.1.5.93 - SOLO-5093
| Code | SOLO-5093 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown when neither the Docker nor the Podman CLI is installed on this machine. The solo cluster-ref state commands need a local container engine to detect and control Kind cluster containers, so without one there is nothing to operate on.
Troubleshooting Steps
- Install Docker Desktop: https://docs.docker.com/get-docker/
- Or install Podman: https://podman.io/docs/installation
- Verify the installation: docker –version (or podman –version)
4.1.5.94 - SOLO-5094
| Code | SOLO-5094 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when solo could not bring the local container engine (Docker Desktop or the Podman machine) into a running state: the platform offers no way to auto-start it (Linux), the start command failed, or the engine did not respond within the startup timeout. The message names the engine and the specific reason.
Troubleshooting Steps
- Start the engine manually (Docker Desktop application, or: podman machine start)
- Verify it is running: docker info (or podman info)
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
4.1.5.95 - SOLO-5095
| Code | SOLO-5095 |
| Category | System |
| Ownership | User |
| Retryable | No |
Description
Thrown by the solo cluster-ref state commands when the container engine is reachable but there is no Kind cluster node container (a container carrying the io.x-k8s.kind.cluster label) for Solo to start, stop, or report on — either none exists at all, or none of the ones that exist are mapped to a Solo cluster reference. Typically the cluster was never created, was deleted (kind delete cluster), or was never connected to Solo.
Troubleshooting Steps
- List existing Kind clusters: kind get clusters
- List the clusters Solo manages: solo cluster-ref config list
- Map an existing cluster to Solo: solo cluster-ref config connect –cluster-ref
–context kind- - Create a cluster with a full deployment: solo one-shot single deploy
4.1.5.96 - SOLO-9001
| Code | SOLO-9001 |
| Category | System |
| Ownership | Infrastructure |
| Retryable | Yes |
Description
Thrown when a bounded operation does not finish within the time solo allows for it. solo guards long-running waits with deadlines — most often while polling for a Kubernetes pod or service to become Ready, but also for Hedera SDK calls and other long-running CLI steps — and raises this once the deadline passes without the expected condition being met. It signals that the operation was still in progress (or stuck), not that it definitively failed, which is why it is retryable: a resource that is merely slow to stabilise often succeeds on a later run or with a larger timeout. It is the base error for more specific timeouts such as PodTerminationTimeoutSoloError and ClusterApiServerTimeoutSoloError.
Troubleshooting Steps
- Check solo logs: tail -n 100 ~/.solo/logs/solo.log
- Verify the target resource or service is responding
- Check Kubernetes pod status: kubectl get pods -A
- Increase the timeout if the operation is expected to take longer
4.1.6 - Internal
4.1.6.1 - SOLO-9002
| Code | SOLO-9002 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when execution reaches a branch that is intentionally not implemented or not supported — for example an abstract operation a subclass was expected to override, a not-yet-built feature path, or an input variant the code does not handle; the message states the reason. Because solo should never route a real command into such a path, this is classified as a defect in solo itself rather than a user or infrastructure problem, and reaching it should be reported with the full error output and the command that triggered it.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.2 - SOLO-9003
| Code | SOLO-9003 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when code reads the remote-configuration runtime state before it has been loaded from the cluster. solo fetches the remote config (a ConfigMap) into memory in an explicit load step that must run before any read, so this is a lifecycle guard: reaching it means a command path accessed the remote config without first loading it, or ran the steps out of order. It indicates a defect in solo rather than a user or infrastructure problem.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.3 - SOLO-9004
| Code | SOLO-9004 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when code modifies or persists the remote configuration before it has been loaded from the cluster. solo must load the remote config (a ConfigMap) into memory before mutating it, so that writes are applied on top of the current cluster state rather than an empty one; this guard fires when a command path attempts a write without that load having run, or runs the steps out of order. It indicates a defect in solo itself.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.4 - SOLO-9005
| Code | SOLO-9005 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when an internal consistency check finds a value that differs from what solo required at that point; the message reports the context together with the expected and actual values. solo uses these assertions to verify invariants as data moves between steps — for example confirming that a downloaded artifact’s checksum matches the expected hash before it is used. A mismatch points to a logic error or a broken assumption inside solo rather than to bad user input or an infrastructure fault, so it is treated as an internal defect and should be reported with the full error output.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.5 - SOLO-9006
| Code | SOLO-9006 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when the logging subsystem is asked for a message group by a key that was never registered. solo groups related log messages under named keys, and this is raised when code references a group that does not exist — typically a typo in the key or a group that was renamed or never added. It points to a defect in solo rather than to user input.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.6 - SOLO-9007
| Code | SOLO-9007 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when a command handler returns false from a path that requires it to return true to signal success; the message names the command namespace and command that did so. solo treats the boolean return of these handlers as a success flag, so a false here means the handler completed without throwing yet reported failure — an unexpected internal outcome that indicates a defect in solo rather than invalid user input.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.7 - SOLO-9008
| Code | SOLO-9008 |
| Category | Internal |
| Ownership | User |
| Retryable | No |
Description
Thrown when the remote configuration contains a component whose type solo does not recognise; the message reports the offending componentType, the solo version recorded in the remote config alongside the running solo version, and the recorded config schema version alongside the highest schema version the running solo supports. solo dispatches on the component type when reading the remote config’s component inventory, and raises this for any value outside the known set. The usual cause is a remote config written by a newer solo than the one running, so it is treated as a cross-version issue the user resolves by aligning solo versions; a hand-edited config can produce the same failure.
Troubleshooting Steps
- Upgrade this Solo to
or newer (npm install -g @hiero-ledger/solo), or rerun the command with the Solo version that wrote the config - If both Solo versions already match, the remote config was likely edited by hand; restore it to its unedited state
4.1.6.8 - SOLO-9010
| Code | SOLO-9010 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when remote-configuration access needs a Kubernetes context to reach the cluster but none is available: no context was passed to the call and solo could not fall back to a default one (for example because the current kubeconfig has no current-context to resolve). Because callers are expected to supply or have already resolved a context by this point, reaching it indicates a broken internal assumption in solo rather than a user error.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.9 - SOLO-9011
| Code | SOLO-9011 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown while rendering cache image targets when a version field holds a value that looks like a template key (all uppercase letters, digits, and underscores) but is not among the declared templates; the message names the offending key. The renderer treats such a value as a reference to a named template and refuses to emit it verbatim, so the key must first be declared in the template set. Reaching it points to a missing template declaration in solo’s configuration rather than to user input.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues
4.1.6.10 - SOLO-9012
| Code | SOLO-9012 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Deliberately thrown by solo’s fault-injection hook to exercise failure and recovery paths during testing — it does not represent a genuine problem with your network or environment. When the SOLO_FAIL_AFTER_STEP environment variable is set, the orchestrator compares it against each step title and raises this error immediately after the matching step completes; the message names that step. If you encounter it without intending to test fault handling, it means SOLO_FAIL_AFTER_STEP is set in your environment — unset it to stop the injected failure.
Troubleshooting Steps
- This error is intended for testing purposes.
- If you did not expect to see this error unset your environment variable: SOLO_FAIL_AFTER_STEP
4.1.6.11 - SOLO-9013
| Code | SOLO-9013 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown to a phase of a parallel orchestration pipeline when a different phase has already failed. When solo deploys network components concurrently, the phases coordinate through an event bus; if one phase throws, the orchestrator aborts the bus so the remaining phases that are waiting on an upstream event stop immediately instead of blocking until their own timeout. This error marks such a downstream cancellation — it is not the root cause. The real failure is carried as this error’s cause and is what solo reports to you; look there (and earlier in the logs) for the phase that actually failed.
Troubleshooting Steps
- This phase did not fail on its own — another phase failed first and the pipeline was aborted.
- Look at the root cause reported above (and earlier in the logs) for the phase that actually failed.
4.1.6.12 - SOLO-9014
| Code | SOLO-9014 |
| Category | Internal |
| Ownership | Solo |
| Retryable | No |
Description
Thrown when solo traps an error that escaped every handler — either an uncaughtException or an unhandledRejection; the message names which of the two fired along with the escaped error’s own message, and the escaped error is wrapped in cause. Reaching this point means a code path failed without being handled where it occurred, which indicates a defect in solo rather than invalid user input.
Troubleshooting Steps
- This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues