Error Codes

• 1: Configuration
• 1.1: SOLO-1001
• 1.2: SOLO-1002
• 1.3: SOLO-1003
• 1.4: SOLO-1004
• 2: Deployment
• 2.1: SOLO-2001
• 2.2: SOLO-2002
• 2.3: SOLO-2003
• 2.4: SOLO-2004
• 2.5: SOLO-2005
• 2.6: SOLO-2006
• 2.7: SOLO-2007
• 2.8: SOLO-2008
• 2.9: SOLO-2009
• 2.10: SOLO-2010
• 2.11: SOLO-2011
• 2.12: SOLO-2012
• 2.13: SOLO-2013
• 2.14: SOLO-2014
• 2.15: SOLO-2015
• 2.16: SOLO-2016
• 2.17: SOLO-2017
• 2.18: SOLO-2018
• 2.19: SOLO-2019
• 2.20: SOLO-2020
• 2.21: SOLO-2021
• 2.22: SOLO-2022
• 2.23: SOLO-2023
• 2.24: SOLO-2024
• 2.25: SOLO-2025
• 2.26: SOLO-2026
• 2.27: SOLO-2027
• 2.28: SOLO-2028
• 2.29: SOLO-2029
• 2.30: SOLO-2030
• 3: Component
• 3.1: SOLO-3001
• 3.2: SOLO-3003
• 3.3: SOLO-3004
• 3.4: SOLO-3005
• 3.5: SOLO-3006
• 3.6: SOLO-3007
• 3.7: SOLO-3008
• 3.8: SOLO-3009
• 3.9: SOLO-3010
• 3.10: SOLO-3011
• 3.11: SOLO-3012
• 3.12: SOLO-3013
• 3.13: SOLO-3014
• 3.14: SOLO-3015
• 3.15: SOLO-3016
• 3.16: SOLO-3017
• 3.17: SOLO-3018
• 3.18: SOLO-3019
• 3.19: SOLO-3021
• 3.20: SOLO-3022
• 3.21: SOLO-3023
• 3.22: SOLO-3024
• 3.23: SOLO-3025
• 3.24: SOLO-3026
• 3.25: SOLO-3027
• 3.26: SOLO-3028
• 3.27: SOLO-3029
• 3.28: SOLO-3030
• 3.29: SOLO-3031
• 3.30: SOLO-3032
• 3.31: SOLO-3033
• 3.32: SOLO-3034
• 3.33: SOLO-3035
• 3.34: SOLO-3036
• 3.35: SOLO-3037
• 3.36: SOLO-3038
• 3.37: SOLO-3039
• 3.38: SOLO-3040
• 3.39: SOLO-3041
• 3.40: SOLO-3042
• 3.41: SOLO-3043
• 3.42: SOLO-3044
• 3.43: SOLO-3045
• 3.44: SOLO-3046
• 3.45: SOLO-3047
• 3.46: SOLO-3048
• 3.47: SOLO-3049
• 3.48: SOLO-3050
• 3.49: SOLO-3051
• 3.50: SOLO-3052
• 3.51: SOLO-3053
• 3.52: SOLO-3054
• 3.53: SOLO-3055
• 3.54: SOLO-3056
• 3.55: SOLO-3057
• 3.56: SOLO-3058
• 3.57: SOLO-3059
• 3.58: SOLO-3060
• 3.59: SOLO-3061
• 3.60: SOLO-3062
• 3.61: SOLO-3063
• 3.62: SOLO-3064
• 3.63: SOLO-3065
• 3.64: SOLO-3066
• 3.65: SOLO-3067
• 3.66: SOLO-3068
• 3.67: SOLO-3069
• 3.68: SOLO-3070
• 3.69: SOLO-3071
• 3.70: SOLO-3072
• 3.71: SOLO-3073
• 3.72: SOLO-3074
• 3.73: SOLO-3075
• 3.74: SOLO-3076
• 3.75: SOLO-3077
• 3.76: SOLO-3078
• 3.77: SOLO-3079
• 3.78: SOLO-3080
• 3.79: SOLO-3081
• 3.80: SOLO-3082
• 3.81: SOLO-3083
• 3.82: SOLO-3084
• 3.83: SOLO-3085
• 3.84: SOLO-3086
• 3.85: SOLO-3087
• 3.86: SOLO-3088
• 3.87: SOLO-3089
• 4: Validation
• 4.1: SOLO-4001
• 4.2: SOLO-4002
• 4.3: SOLO-4003
• 4.4: SOLO-4004
• 4.5: SOLO-4005
• 4.6: SOLO-4006
• 4.7: SOLO-4007
• 4.8: SOLO-4008
• 4.9: SOLO-4009
• 4.10: SOLO-4010
• 4.11: SOLO-4011
• 4.12: SOLO-4012
• 4.13: SOLO-4013
• 4.14: SOLO-4014
• 4.15: SOLO-4015
• 4.16: SOLO-4016
• 4.17: SOLO-4017
• 4.18: SOLO-4018
• 4.19: SOLO-4019
• 4.20: SOLO-4020
• 4.21: SOLO-4021
• 4.22: SOLO-4022
• 4.23: SOLO-4023
• 4.24: SOLO-4024
• 4.25: SOLO-4025
• 4.26: SOLO-4026
• 4.27: SOLO-4027
• 4.28: SOLO-4028
• 4.29: SOLO-4029
• 4.30: SOLO-4030
• 4.31: SOLO-4031
• 4.32: SOLO-4032
• 4.33: SOLO-4033
• 4.34: SOLO-4034
• 4.35: SOLO-4035
• 4.36: SOLO-4036
• 4.37: SOLO-4037
• 4.38: SOLO-4038
• 4.39: SOLO-4039
• 4.40: SOLO-4040
• 4.41: SOLO-4041
• 4.42: SOLO-4042
• 4.43: SOLO-4043
• 4.44: SOLO-4044
• 4.45: SOLO-4045
• 4.46: SOLO-4046
• 4.47: SOLO-4047
• 4.48: SOLO-4048
• 4.49: SOLO-4049
• 4.50: SOLO-4050
• 4.51: SOLO-4051
• 4.52: SOLO-4052
• 4.53: SOLO-4053
• 4.54: SOLO-4054
• 4.55: SOLO-4055
• 4.56: SOLO-4056
• 4.57: SOLO-4057
• 4.58: SOLO-4058
• 4.59: SOLO-4059
• 4.60: SOLO-4060
• 4.61: SOLO-4061
• 4.62: SOLO-4062
• 4.63: SOLO-4063
• 4.64: SOLO-4064
• 4.65: SOLO-4065
• 4.66: SOLO-4066
• 4.67: SOLO-4067
• 4.68: SOLO-4068
• 4.69: SOLO-4069
• 4.70: SOLO-4070
• 4.71: SOLO-4071
• 4.72: SOLO-4072
• 4.73: SOLO-4073
• 4.74: SOLO-4074
• 4.75: SOLO-4075
• 4.76: SOLO-4076
• 5: System
• 5.1: SOLO-5001
• 5.2: SOLO-5002
• 5.3: SOLO-5003
• 5.4: SOLO-5004
• 5.5: SOLO-5005
• 5.6: SOLO-5006
• 5.7: SOLO-5007
• 5.8: SOLO-5008
• 5.9: SOLO-5009
• 5.10: SOLO-5010
• 5.11: SOLO-5011
• 5.12: SOLO-5012
• 5.13: SOLO-5013
• 5.14: SOLO-5014
• 5.15: SOLO-5015
• 5.16: SOLO-5016
• 5.17: SOLO-5017
• 5.18: SOLO-5018
• 5.19: SOLO-5019
• 5.20: SOLO-5020
• 5.21: SOLO-5021
• 5.22: SOLO-5022
• 5.23: SOLO-5023
• 5.24: SOLO-5024
• 5.25: SOLO-5025
• 5.26: SOLO-5026
• 5.27: SOLO-5027
• 5.28: SOLO-5028
• 5.29: SOLO-5029
• 5.30: SOLO-5030
• 5.31: SOLO-5031
• 5.32: SOLO-5032
• 5.33: SOLO-5033
• 5.34: SOLO-5034
• 5.35: SOLO-5035
• 5.36: SOLO-5036
• 5.37: SOLO-5037
• 5.38: SOLO-5038
• 5.39: SOLO-5039
• 5.40: SOLO-5040
• 5.41: SOLO-5041
• 5.42: SOLO-5042
• 5.43: SOLO-5043
• 5.44: SOLO-5044
• 5.45: SOLO-5045
• 5.46: SOLO-5046
• 5.47: SOLO-5047
• 5.48: SOLO-5048
• 5.49: SOLO-5049
• 5.50: SOLO-5050
• 5.51: SOLO-5051
• 5.52: SOLO-5052
• 5.53: SOLO-5053
• 5.54: SOLO-5054
• 5.55: SOLO-5055
• 5.56: SOLO-5056
• 5.57: SOLO-5057
• 5.58: SOLO-5058
• 5.59: SOLO-5059
• 5.60: SOLO-5060
• 5.61: SOLO-5061
• 5.62: SOLO-5062
• 5.63: SOLO-5063
• 5.64: SOLO-5064
• 5.65: SOLO-5065
• 5.66: SOLO-5066
• 5.67: SOLO-5067
• 5.68: SOLO-5068
• 5.69: SOLO-5069
• 5.70: SOLO-5070
• 5.71: SOLO-5071
• 5.72: SOLO-5072
• 5.73: SOLO-5073
• 5.74: SOLO-9001
• 6: Internal
• 6.1: SOLO-9002
• 6.2: SOLO-9003
• 6.3: SOLO-9004
• 6.4: SOLO-9005
• 6.5: SOLO-9006
• 6.6: SOLO-9007
• 6.7: SOLO-9008
• 6.8: SOLO-9009
• 6.9: SOLO-9010
• 6.10: SOLO-9011
• 6.11: SOLO-9012

1 - Configuration

1.1 - SOLO-1001

LocalConfigNotFoundSoloError

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. The file is missing because solo init has not yet run on this machine, because SOLO_HOME points at a different directory than the one the file was created in, or because it was manually moved or deleted.

Troubleshooting Steps

1. Create a local config: solo deployment config create –deployment –namespace

1.2 - SOLO-1002

WriteLocalConfigFileError

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

1. Check file system permissions for ~/.solo

1.3 - SOLO-1003

RefreshLocalConfigSourceError

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 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.

Troubleshooting Steps

1. Check file system permissions for ~/.solo
2. Verify the config file exists: solo deployment config info

1.4 - SOLO-1004

RemoteConfigsMismatchSoloError

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

1. Inspect both configs: kubectl get configmap -n
2. Sync manually before retrying

2 - Deployment

2.1 - SOLO-2001

CreateDeploymentSoloError

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

1. Check the logs for details: tail -n 100 ~/.solo/logs/solo.log

2.2 - SOLO-2002

DeploymentAlreadyExistsSoloError

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

1. Check existing deployments: solo deployment config list
2. Choose a different name for your deployment

2.3 - SOLO-2003

DeploymentNotFoundError

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

1. List available deployments: solo deployment config list
2. Create a deployment if needed: solo deployment config create

2.4 - SOLO-2004

DeploymentHasRemoteResourcesError

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

1. Destroy all components in the deployment before deleting it:
2. solo mirror node destroy
3. solo relay node destroy
4. solo explorer node destroy
5. solo block node destroy
6. solo consensus network destroy

2.5 - SOLO-2005

DeploymentDeleteFailedError

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

1. Check logs for details: tail -n 100 ~/.solo/logs/solo.log
2. Verify cluster references and their contexts are valid: solo cluster-ref config list

2.6 - SOLO-2006

ClusterAddFailedError

Description

Thrown when attaching a cluster to a deployment fails; the underlying failure is wrapped in cause. Attaching binds a registered cluster reference (and its kubeconfig context) to the deployment so components can be placed there, so this is raised when that step cannot complete — commonly because the cluster reference has not been created/connected yet, the kubeconfig context does not exist, or the cluster is unreachable. It is retryable, since a transient connectivity issue often clears once the reference and context are valid.

Troubleshooting Steps

1. Verify the cluster context exists: kubectl config get-contexts
2. Make sure the cluster reference is created: cluster-ref config connect
3. Check logs for details: tail -n 100 ~/.solo/logs/solo.log

2.7 - SOLO-2007

DeploymentListFailedError

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

1. Check logs for details: tail -n 100 ~/.solo/logs/solo.log

2.8 - SOLO-2008

ClusterReferenceNotFoundError

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

1. List available cluster references: solo cluster-ref config list
2. Connect a cluster: solo cluster-ref config connect

2.9 - SOLO-2009

ClusterReferenceAlreadyExistsError

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

1. List current cluster references: solo cluster-ref config list
2. Disconnect it first if you want to re-add it: solo cluster-ref config disconnect

2.10 - SOLO-2010

NamespaceNotSetError

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

1. Ensure a namespace is specified: pass –namespace to your command
2. Check deployment config: solo deployment config info –deployment

2.11 - SOLO-2011

NoClustersForDeploymentError

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

1. Attach a cluster to the deployment: solo deployment cluster attach –deployment

2.12 - SOLO-2012

ClusterReferenceResolutionFailedError

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

1. Verify the deployment has clusters attached: solo deployment config info
2. Attach the cluster reference to the deployment: solo deployment cluster attach

2.13 - SOLO-2013

ContextNotFoundForClusterError

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

1. Connect a kubeconfig context to the cluster: solo cluster-ref config connect

2.14 - SOLO-2014

NoDeploymentsFoundError

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

1. Create a deployment: solo deployment config create

2.15 - SOLO-2015

DeploymentListPortsFailedError

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

1. Check logs for details: tail -n 100 ~/.solo/logs/solo.log
2. Verify the Kubernetes API server is reachable: kubectl cluster-info
3. List port-forwards in the namespace to check for any issues: kubectl get port-forwards -n

2.16 - SOLO-2016

ClusterSetupFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List installed Helm releases: helm list -A
3. Inspect cluster pods: kubectl get pods -A
4. Re-run cluster setup: solo cluster-ref config setup

2.17 - SOLO-2017

ClusterResetFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect cluster state: kubectl get pods -A
3. Check Helm releases still present: helm list -A
4. Re-run cluster reset: solo cluster-ref config reset

2.18 - SOLO-2018

MinioInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect cluster state: kubectl get pods -A
3. Check Helm release status: helm list -A
4. Verify cluster connectivity: kubectl cluster-info

2.19 - SOLO-2019

PrometheusInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect cluster pods: kubectl get pods -A
3. Check Helm release status: helm list -A
4. Verify cluster connectivity: kubectl cluster-info

2.20 - SOLO-2020

MetricsServerInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect cluster pods: kubectl get pods -A
3. Check Helm release status: helm list -A
4. Verify cluster connectivity: kubectl cluster-info

2.21 - SOLO-2021

ClusterRoleInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify RBAC permissions: kubectl get clusterroles
3. Inspect cluster state: kubectl get pods -A

2.22 - SOLO-2022

ClusterApiServerTimeoutSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the cluster context is reachable: kubectl cluster-info –context
3. Check cluster node status: kubectl get nodes
4. Inspect cluster pods: kubectl get pods -A

2.23 - SOLO-2023

KindClusterNetworkSetupFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Docker is running: docker ps
3. Check existing Kind clusters: kind get clusters
4. Verify Helm repository access: helm repo list

2.24 - SOLO-2024

BackupExportFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes connectivity: kubectl get pods -A
3. Check that the deployment exists: solo deployment config list
4. Run backup again: solo config ops backup

2.25 - SOLO-2025

BackupImportFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes connectivity: kubectl get pods -A
3. Verify the backup archive is complete and valid
4. Run restore: solo config ops restore-config

2.26 - SOLO-2026

BackupRestoreClustersFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the backup archive is valid and the input directory is correct
3. Check Docker or Kind cluster availability: kind get clusters
4. Run cluster restore: solo config ops restore-clusters

2.27 - SOLO-2027

DeployNetworkFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect consensus node pods: kubectl get pods -A
3. Check Helm release status: helm list -A
4. Verify cluster connectivity: kubectl cluster-info

2.28 - SOLO-2028

InitFailedSoloError

Description

Thrown when solo init cannot complete the one-time setup it performs before other commands can run; when a cause is available its message is appended. solo init prepares the local environment — creating the ~/.solo working directory and verifying or installing the required external tools (kubectl, helm, kind, docker). This error means one of those steps failed, most often because a prerequisite is missing or could not be installed, or the working directory could not be created.

Troubleshooting Steps

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify all prerequisites are installed (kubectl, helm, kind, docker)
3. Re-run initialization: solo init

2.29 - SOLO-2029

BlockNodeClusterContextNotFoundSoloError

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

1. List registered cluster references: solo cluster-ref config list
2. Verify the block node is associated with a registered cluster
3. Check deployment configuration: solo deployment config info

2.30 - SOLO-2030

MirrorNodeClusterContextNotFoundSoloError

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

1. List registered cluster references: solo cluster-ref config list
2. Verify the mirror node is associated with a registered cluster
3. Check deployment configuration: solo deployment config info

3 - Component

3.1 - SOLO-3001

NodeTransactionFailedSoloError

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

1. Check the solo logs for details: tail -n 100 ~/.solo/logs/solo.log
2. Verify the node pod is running: kubectl get pods -n -l solo.hedera.com/type=network-node
3. Consult the Hedera documentation for the meaning of the status code

3.2 - SOLO-3003

NodeBuildUploadFailedSoloError

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

1. Review solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check node pod status: kubectl get pods -n -l solo.hedera.com/type=network-node
3. Inspect the pod for more detail: kubectl describe pod -n

3.3 - SOLO-3004

NodeBuildCopyFailedSoloError

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

1. Check pod status: kubectl get pods -n -l solo.hedera.com/type=network-node
2. Verify the local build path is valid and readable
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.4 - SOLO-3005

NodeJfrExecutionFailedSoloError

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

1. Check if the node pod is running: kubectl get pod -n
2. Verify the pod has jcmd available: kubectl exec -n – which jcmd
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.5 - SOLO-3006

NodeJfrPidNotFoundSoloError

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

1. Verify the consensus node is running inside the pod: kubectl exec – ps axww -o pid,command
2. Check node startup logs: kubectl logs -n
3. Restart the node if ServicesMain is absent: solo consensus node restart

3.6 - SOLO-3007

NodeDebugArchiveFailedSoloError

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

1. Verify the output directory is writable
2. Check available disk space: df -h
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.7 - SOLO-3008

BlockNodeConfigFailedSoloError

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

1. Check block node pod status: kubectl get pods -n -l block-node.hiero.com/type=block-node
2. Check network node pod status: kubectl get pods -n -l solo.hedera.com/type=network-node
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4. Verify the cluster is reachable: kubectl cluster-info –context

3.8 - SOLO-3009

ChartInstallFailedSoloError

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

1. Check Helm release status: helm list -n
2. Review Helm errors: helm status -n
3. Verify the cluster is reachable: kubectl cluster-info –context
4. Retry after inspecting solo logs: tail -n 100 ~/.solo/logs/solo.log

3.9 - SOLO-3010

NetworkDestroyFailedSoloError

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

1. Check remaining Helm releases: helm list -A
2. Check for stuck namespaces: kubectl get namespaces
3. Manually clean up: helm uninstall -n
4. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.10 - SOLO-3011

NodeNotReadySoloError

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

1. Check node pod status: kubectl get pods -n -l solo.hedera.com/node-name=
2. View node logs: kubectl logs -n -l solo.hedera.com/node-name=
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.11 - SOLO-3012

RapidFireExecutionSoloError

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

1. Check NLG pod logs for TPS output and errors: kubectl logs -n -l app.kubernetes.io/instance=network-load-generator
2. Retry with lower load parameters or a reduced –max-tps value

3.12 - SOLO-3013

NodeStakeTransactionErrorSoloError

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

1. Verify the treasury account has sufficient HBAR balance.
2. Confirm the node is in ACTIVE status: kubectl get pods -n -l solo.hedera.com/type=network-node
3. Check gRPC connectivity to the consensus node.
4. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.13 - SOLO-3014

NodePrepareUpgradeTransactionErrorSoloError

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

1. Verify the node admin key is correct and loaded from the k8s secret.
2. Confirm the freeze admin account has sufficient HBAR balance.
3. Verify the upgrade zip file hash is correct.
4. Check node client connection to the consensus network.
5. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.14 - SOLO-3015

NodeFreezeUpgradeTransactionErrorSoloError

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

1. Verify the node admin key is correct and loaded from the k8s secret.
2. Confirm the freeze admin account has sufficient HBAR balance.
3. Verify the nodes have completed the prepare upgrade step.
4. Verify gossip endpoints and gRPC service endpoints are reachable from the network.
5. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.15 - SOLO-3016

NodeFreezeTransactionErrorSoloError

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

1. Verify the node admin key is correct and loaded from the k8s secret.
2. Confirm the freeze admin account has the correct operator key set.
3. Verify the freeze admin account has sufficient HBAR balance.
4. Verify gossip endpoints and gRPC service endpoints are reachable from the network.
5. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.16 - SOLO-3017

NodeUpdateTransactionErrorSoloError

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

1. Verify the node admin key is correct and loaded from the k8s secret.
2. Confirm the node client is connected to the consensus network.
3. Check if the new account number is valid and funded.
4. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.17 - SOLO-3018

NodeDeleteTransactionErrorSoloError

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

1. Verify the node admin key is correct and loaded from the k8s secret.
2. Confirm the node exists in the current address book.
3. Verify gossip endpoints and gRPC service endpoints are reachable from the network.
4. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.18 - SOLO-3019

NodeCreateTransactionErrorSoloError

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

1. Verify gossip endpoints and gRPC service endpoints are reachable from the network.
2. Confirm the admin key is valid and the account has sufficient HBAR.
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.19 - SOLO-3021

AccountBalanceQueryFailedSoloError

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

1. Verify gossip endpoints and gRPC service endpoints are reachable from the network.
2. Confirm the account ID is valid and exists on the network.
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

3.20 - SOLO-3022

ExplorerDeployFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect explorer pods: kubectl get pods -A -l app.kubernetes.io/component=hiero-explorer
3. Inspect Helm release: helm status -n

3.21 - SOLO-3023

ExplorerUpgradeFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect Helm release: helm status -n
3. View explorer pod logs: kubectl logs -n

3.22 - SOLO-3024

ExplorerDestroyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List Helm releases: helm list -A
3. Force-uninstall if stuck: helm uninstall -n

3.23 - SOLO-3025

RelayDeployFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect relay pods: kubectl get pods -A -l app.kubernetes.io/instance=relay-
3. Inspect Helm release: helm status -n

3.24 - SOLO-3026

RelayUpgradeFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect Helm release: helm status -n
3. View relay pod logs: kubectl logs -n

3.25 - SOLO-3027

RelayDestroyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List Helm releases: helm list -A
3. Force-uninstall if stuck: helm uninstall -n

3.26 - SOLO-3028

RelayNotRunningSoloError

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

1. Check relay pod status: kubectl get pods -A | grep
2. View relay pod logs: kubectl logs -n -l app.kubernetes.io/instance=
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

3.27 - SOLO-3029

RelayNotReadySoloError

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

1. Check relay pod status: kubectl get pods -A | grep
2. Describe relay pods to check readiness probe failures: kubectl describe pods -A -l app.kubernetes.io/instance=
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

3.28 - SOLO-3030

RelayOperatorKeyRetrievalFailedSoloError

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

1. Verify K8s API connectivity: kubectl get pods -n
2. If an operator key secret exists, verify it has a privateKey field: kubectl get secret -n -o yaml | grep privateKey
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

3.29 - SOLO-3031

MirrorNodeDeployFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect mirror node pods: kubectl get pods -A -l app.kubernetes.io/instance=mirror-
3. Inspect Helm release: helm status -n

3.30 - SOLO-3032

MirrorNodeUpgradeFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect Helm release: helm status -n
3. View mirror node pod logs: kubectl logs -n

3.31 - SOLO-3033

MirrorNodeDestroyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List Helm releases: helm list -A
3. Force-uninstall if stuck: helm uninstall -n

3.32 - SOLO-3034

MirrorNodeOperatorKeyRetrievalFailedSoloError

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

1. Verify K8s API connectivity: kubectl get pods -n
2. If an operator key secret exists, verify it has a privateKey field: kubectl get secret -n -o yaml | grep privateKey
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

3.33 - SOLO-3035

OneShotDeployFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. If rollback was skipped, clean up partial resources: solo one-shot single destroy

3.34 - SOLO-3036

OneShotDestroyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List remaining Helm releases: helm list -A
3. Delete stuck resources manually: kubectl delete -n

3.35 - SOLO-3037

OneShotDeploymentInfoRetrievalFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify kubeconfig context is valid: kubectl cluster-info

3.36 - SOLO-3038

FalconValuesPreparationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the profile YAML is valid: solo deployment profile validate

3.37 - SOLO-3039

BlockNodeDeployFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
3. Inspect Helm release: helm status -n
4. Check Helm history: helm history -n

3.38 - SOLO-3040

BlockNodeDestroyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
3. Inspect Helm release: helm status -n
4. Check Helm history: helm history -n

3.39 - SOLO-3041

BlockNodeUpgradeFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
3. Inspect Helm release: helm status -n
4. Check Helm history: helm history -n

3.40 - SOLO-3042

BlockNodeAddExternalFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect the remote config for the registered node: solo deployment config info
3. Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
4. If the issue persists, report it with your solo log

3.41 - SOLO-3043

BlockNodeDeleteExternalFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect the remote config for the registered node: solo deployment config info
3. Inspect block node pods: kubectl get pods -A -l block-node.hiero.com/type=block-node
4. If the issue persists, report it with your solo log

3.42 - SOLO-3044

BlockNodeHealthCheckFailedSoloError

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

1. Check block node pod status: kubectl get pods -A -l block-node.hiero.com/type=block-node
2. Verify liveness endpoint manually: kubectl exec -n – curl http://localhost:/healthz/readyz
3. Check pod logs: kubectl logs -n -l block-node.hiero.com/type=block-node
4. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

3.43 - SOLO-3045

RapidFireLoadStartFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check NLG pod status: kubectl get pods -n -l app.kubernetes.io/instance=network-load-generator
3. Describe NLG pods for scheduling or image-pull errors: kubectl describe pods -n -l app.kubernetes.io/instance=network-load-generator
4. Check the NLG Helm release: helm status network-load-generator -n

3.44 - SOLO-3046

RapidFireLoadStopFailedSoloError

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

1. Check solo logs for the root cause: tail -n 100 ~/.solo/logs/solo.log
2. Check NLG pod status: kubectl get pods -n -l app.kubernetes.io/instance=network-load-generator
3. Check for running NLG Java processes: kubectl exec -n – ps aux | grep java
4. To force-stop, uninstall the NLG chart: helm uninstall network-load-generator -n

3.45 - SOLO-3047

RapidFireKillFailedSoloError

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

1. Check if the test process is still running: kubectl exec -n – ps aux | grep
2. Manually kill the process: kubectl exec -n – pkill -f
3. To stop the load test entirely, uninstall the NLG chart: helm uninstall network-load-generator -n

3.46 - SOLO-3048

AccountCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Check node logs for errors: kubectl logs -n
4. Create a new account: solo ledger account create

3.47 - SOLO-3049

AccountKeyUpdateFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify the account ID is correct and the account exists on the network

3.48 - SOLO-3050

AccountKeysBatchUpdateFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify operator account has sufficient permissions
4. Update individual accounts: solo ledger account update

3.49 - SOLO-3051

AccountTransferFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify the sender account has sufficient HBAR balance

3.50 - SOLO-3052

AccountInfoFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify the account ID exists on the network

3.51 - SOLO-3053

AccountUpdateFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify the account exists on the network: solo ledger account update

3.52 - SOLO-3054

AccountSecretCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes connectivity: kubectl get pods -n
3. Check existing secrets: kubectl get secrets -n
4. Verify RBAC permissions allow secret creation

3.53 - SOLO-3055

EvmAddressRetrievalFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Verify the account ID is valid and the account exists on the network

3.54 - SOLO-3056

NodeAccessConfigFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus node pods are running: kubectl get pods -n
3. Check node logs: kubectl logs -n
4. Restart the consensus node: solo consensus node restart

3.55 - SOLO-3057

NodeClientLoadFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus node pods are running: kubectl get pods -n
3. Inspect node pod logs: kubectl logs -n
4. Verify network port-forwards are active: solo deployment refresh port-forwards

3.56 - SOLO-3058

NodeClientRefreshFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus node pods are running: kubectl get pods -n
3. Inspect node pod logs: kubectl logs -n
4. Verify network port-forwards are active: solo deployment refresh port-forwards

3.57 - SOLO-3059

NodeClientSetupFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus node pods are running: kubectl get pods -n
3. Check port-forward status: solo deployment refresh port-forwards
4. Inspect node logs: kubectl logs -n

3.58 - SOLO-3060

SdkPingFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the node pod is running: kubectl get pods -n -l solo.hedera.com/node-name=
3. Inspect node logs: kubectl logs -n
4. Check port-forward status: solo deployment refresh port-forwards
5. Restart the node: solo consensus node restart

3.59 - SOLO-3061

NodeServicesRetrievalFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List Kubernetes services in the namespace: kubectl get svc -n
3. Verify consensus nodes are deployed: kubectl get pods -n

3.60 - SOLO-3062

GossipKeySecretCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check existing secrets: kubectl get secrets -n
3. Verify RBAC permissions allow secret creation in the namespace
4. Re-run node setup: solo consensus node setup

3.61 - SOLO-3063

TlsKeySecretCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check existing secrets: kubectl get secrets -n
3. Verify RBAC permissions allow secret creation in the namespace
4. Re-run node setup: solo consensus node setup

3.62 - SOLO-3064

TlsKeyGenerationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify required key generation tools are available
3. Re-run node setup: solo consensus node setup

3.63 - SOLO-3065

SigningKeyGenerationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify key generation tools are available
3. Re-run key generation: solo keys consensus

3.64 - SOLO-3066

GrpcTlsKeyGenerationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify key generation tools are available
3. Re-run node setup: solo consensus node setup

3.65 - SOLO-3067

GrpcTlsCertMismatchSoloError

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

1. Ensure the number of certificate paths matches the number of key paths
2. Each certificate must have a corresponding private key in the same position
3. Verify the certificate and key files exist at the specified paths

3.66 - SOLO-3068

GrpcWebTlsCertMismatchSoloError

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

1. Ensure the number of certificate paths matches the number of key paths
2. Each certificate must have a corresponding private key in the same position
3. Verify the certificate and key files exist at the specified paths

3.67 - SOLO-3069

CertificateSecretCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check existing secrets: kubectl get secrets -n
3. Verify RBAC permissions allow secret creation
4. Re-run node setup: solo consensus node setup

3.68 - SOLO-3070

CertificateParsingFailedSoloError

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

1. Verify the certificate input format is correct for the expected type
2. Check the value at line , position of the input
3. Ensure certificate values are properly formatted (PEM or DER encoded)

3.69 - SOLO-3071

CertificateFileNotFoundSoloError

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

1. Verify the file exists at the path:
2. Ensure the path is absolute or relative to the working directory
3. Check file permissions allow reading the certificate file

3.70 - SOLO-3072

ExplorerTlsSecretCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check existing secrets: kubectl get secrets -n
3. Verify RBAC permissions allow secret creation
4. Re-deploy the explorer: solo explorer node add

3.71 - SOLO-3073

PlatformFileNotFoundSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the file exists at:
3. Ensure the node build artifacts are present and the build path is correct

3.72 - SOLO-3074

PlatformFileCopyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the pod is running: kubectl get pod -n
3. Check available disk space in the pod
4. Inspect pod logs: kubectl logs -n

3.73 - SOLO-3075

PlatformKeyFileMissingSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the key file exists at:
3. Re-generate keys if needed: solo keys consensus
4. Re-run node setup: solo consensus node setup

3.74 - SOLO-3076

GenesisAdminKeySecretFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check existing secrets: kubectl get secrets -n
3. Verify RBAC permissions allow secret creation
4. Redeploy the network: solo consensus network deploy

3.75 - SOLO-3077

GenesisDataGenerationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify all consensus node configurations are correct
3. Check deployment configuration: solo deployment config info
4. Redeploy the network: solo consensus network deploy

3.76 - SOLO-3078

PostgresInitScriptCopyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the Postgres pod is running: kubectl get pods -n -l app.kubernetes.io/name=postgresql
3. Inspect Postgres pod logs: kubectl logs -n
4. Re-deploy the mirror node: solo mirror node add

3.77 - SOLO-3079

PostgresInitScriptFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect Postgres pod logs: kubectl logs -n
3. Check Postgres pod status: kubectl describe pod -n
4. Re-deploy the mirror node: solo mirror node add

3.78 - SOLO-3080

MirrorPasswordSecretMissingSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect the mirror-passwords secret: kubectl get secret mirror-passwords -n -o jsonpath="{.data}"
3. Re-deploy the mirror node to recreate secrets: solo mirror node add

3.79 - SOLO-3081

FileContentVerificationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running and healthy: kubectl get pods -n
3. Inspect node logs for errors: kubectl logs -n

3.80 - SOLO-3082

HederaFileCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Consult the Hedera documentation for the meaning of the status code

3.81 - SOLO-3083

HederaFileUpdateFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Consult the Hedera documentation for the meaning of the status code

3.82 - SOLO-3084

HederaFileAppendFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Consult the Hedera documentation for the meaning of the status code

3.83 - SOLO-3085

NodeStatusEmptyResponseSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the consensus node pod is running: kubectl get pods -n
3. Inspect node logs: kubectl logs -n

3.84 - SOLO-3086

NodeStatusMissingLineSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the consensus node pod is running: kubectl get pods -n
3. Inspect node logs: kubectl logs -n

3.85 - SOLO-3087

PredefinedAccountsCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify consensus nodes are running: kubectl get pods -n
3. Check node logs for errors: kubectl logs -n

3.86 - SOLO-3088

FileContentMismatchSoloError

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

1. Retry the file upload — transient network issues can cause partial or corrupt writes
2. Check solo logs for chunk append errors: tail -n 100 ~/.solo/logs/solo.log
3. Verify consensus nodes are healthy: kubectl get pods -n
4. Check node logs for transaction errors: kubectl logs -n
5. Confirm no concurrent process modified the same Hedera file during the upload

3.87 - SOLO-3089

NodeServiceNotFoundSoloError

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

1. Verify that node ‘’ exists in the deployment: solo deployment info
2. List all node services in the namespace: kubectl get svc -n
3. Check that the consensus node pod is running: kubectl get pods -n -l app=
4. Check solo logs for more context: tail -n 100 ~/.solo/logs/solo.log

4 - Validation

4.1 - SOLO-4001

MissingArgumentError

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

1. Provide the missing argument. Run solo –help for usage information

4.2 - SOLO-4002

IllegalArgumentError

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

1. An argument has an valid value or format.
2. Verify the argument value before retrying

4.3 - SOLO-4003

InvalidOutputFormatError

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

1. Valid output formats are: json, yaml, wide

4.4 - SOLO-4004

ConsensusNodeCountRequiredError

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

1. Specify the number of consensus nodes using the – flag, e.g. – 3

4.5 - SOLO-4005

InvalidPortNumberError

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

1. Port numbers must be integers between 1 and 65535

4.6 - SOLO-4006

LocalBuildPathNotFoundSoloError

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

1. Verify the path exists: ls -la
2. Set the correct path: solo consensus node setup –local-build-path
3. Build the platform locally and point to the data/ directory output

4.7 - SOLO-4007

LocalBuildMissingSubdirectoriesSoloError

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

1. Verify the directory structure: ls -la
2. Ensure the path points to the data/ directory of the Hedera platform build
3. Expected layout: /apps/.jar and /lib/.jar (set via –local-build-path)

4.8 - SOLO-4008

LocalBuildNoJarFilesSoloError

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

1. List files in the directory: ls -la
2. Ensure a complete platform build was performed before using –local-build-path
3. Expected: /apps/HederaNode.jar and /lib/*.jar

4.9 - SOLO-4009

NodeJarFilesNotInContainerSoloError

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

1. Run setup before starting: solo consensus node setup
2. Verify the directory inside the pod: kubectl exec -n – ls
3. Re-copy platform software: solo consensus node setup –local-build-path

4.10 - SOLO-4010

GrpcEndpointsRequiredSoloError

Description