System

• 1: SOLO-5001
• 2: SOLO-5002
• 3: SOLO-5003
• 4: SOLO-5004
• 5: SOLO-5005
• 6: SOLO-5006
• 7: SOLO-5007
• 8: SOLO-5008
• 9: SOLO-5009
• 10: SOLO-5010
• 11: SOLO-5011
• 12: SOLO-5012
• 13: SOLO-5013
• 14: SOLO-5014
• 15: SOLO-5015
• 16: SOLO-5016
• 17: SOLO-5017
• 18: SOLO-5018
• 19: SOLO-5019
• 20: SOLO-5020
• 21: SOLO-5021
• 22: SOLO-5022
• 23: SOLO-5023
• 24: SOLO-5024
• 25: SOLO-5025
• 26: SOLO-5026
• 27: SOLO-5027
• 28: SOLO-5028
• 29: SOLO-5029
• 30: SOLO-5030
• 31: SOLO-5031
• 32: SOLO-5032
• 33: SOLO-5033
• 34: SOLO-5034
• 35: SOLO-5035
• 36: SOLO-5036
• 37: SOLO-5037
• 38: SOLO-5038
• 39: SOLO-5039
• 40: SOLO-5040
• 41: SOLO-5041
• 42: SOLO-5042
• 43: SOLO-5043
• 44: SOLO-5044
• 45: SOLO-5045
• 46: SOLO-5046
• 47: SOLO-5047
• 48: SOLO-5048
• 49: SOLO-5049
• 50: SOLO-5050
• 51: SOLO-5051
• 52: SOLO-5052
• 53: SOLO-5053
• 54: SOLO-5054
• 55: SOLO-5055
• 56: SOLO-5056
• 57: SOLO-5057
• 58: SOLO-5058
• 59: SOLO-5059
• 60: SOLO-5060
• 61: SOLO-5061
• 62: SOLO-5062
• 63: SOLO-5063
• 64: SOLO-5064
• 65: SOLO-5065
• 66: SOLO-5066
• 67: SOLO-5067
• 68: SOLO-5068
• 69: SOLO-5069
• 70: SOLO-5070
• 71: SOLO-5071
• 72: SOLO-5072
• 73: SOLO-5073
• 74: SOLO-9001

1 - SOLO-5001

ResourceNotFoundError

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

1. Make sure the requested resource exists and is reachable, if not file a bug report: https://github.com/hiero-ledger/solo/issues

2 - SOLO-5002

ClusterConnectionFailedError

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

1. Verify the kubeconfig context is correct and the cluster is reachable: kubectl cluster-info –context

3 - SOLO-5003

PortForwardRefreshFailedError

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

1. Check the all pods exist and are running: kubectl get pods -n
2. Check the port-forwards of your deployment: solo deployment config ports –deployment
3. Restart the port-forward: solo deployment refresh port-forwards –deployment

4 - SOLO-5004

PortForwardStatusFailedError

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

1. Check the all pods exist and are running: kubectl get pods -n
2. Restart the port-forward: solo deployment refresh port-forwards –deployment

5 - SOLO-5005

NamespaceNotFoundSoloError

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

1. List existing namespaces: kubectl get namespaces
2. Check the active deployment: solo deployment config info –deployment
3. Redeploy the network to re-create the namespace: solo consensus network deploy

6 - SOLO-5006

PodNotFoundSoloError

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

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

7 - SOLO-5007

HaproxyPodsNotFoundSoloError

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

1. Check HAProxy pod status: kubectl get pods -n -l solo.hedera.com/type=haproxy
2. Check the active deployment: solo deployment config info –deployment
3. Redeploy the network if HAProxy is missing: solo consensus network deploy

8 - SOLO-5008

LoadBalancerNotFoundSoloError

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

1. Check load balancer service status: kubectl get svc -n -l solo.hedera.com/type=network-node
2. Ensure your cloud provider supports LoadBalancer services
3. Review cloud provisioning logs for LB assignment delays

9 - SOLO-5009

KubeContextNotFoundSoloError

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

1. Check active deployments: solo deployment config info
2. Verify that the node alias is registered: kubectl get configmap -n -o yaml
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

10 - SOLO-5010

ConsensusNodeNotInConfigSoloError

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

1. List registered nodes: solo deployment config info –deployment
2. Verify the node alias: kubectl get configmap -n -o yaml | grep nodeAlias
3. Re-run with a valid alias: solo node –node-aliases

11 - SOLO-5011

K8sSecretCreateFailedSoloError

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

1. Check RBAC permissions: kubectl auth can-i create secrets -n
2. Inspect existing secrets: kubectl get secrets -n
3. Review solo logs: tail -n 100 ~/.solo/logs/solo.log
4. Verify the cluster is reachable: kubectl cluster-info –context

12 - SOLO-5012

StatesDirectoryNotFoundSoloError

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

1. Verify the states directory exists: ls -la
2. Check that the state download succeeded: solo consensus node states
3. Use the correct –inputDir path structure: /states///

13 - SOLO-5013

PortForwardMissingSoloError

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

1. Check port-forward status: solo deployment diagnostics connections –deployment
2. Re-establish port forwards: solo consensus node start
3. Verify the pod is running: kubectl get pods -n

14 - SOLO-5014

NoPvcFoundSoloError

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

1. Redeploy with PVCs enabled: solo consensus network deploy –pvcs true

15 - SOLO-5015

ClusterReferenceUndeterminedSoloError

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

1. Check the remote config: kubectl get configmap -n -o yaml
2. Verify cluster references: solo deployment config info –deployment
3. Re-initialize solo if needed: solo init
4. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

16 - SOLO-5016

UpgradeVersionFetchFailedSoloError

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

1. Check internet connectivity
2. Verify the version exists: https://github.com/hashgraph/hedera-services/releases
3. Retry the upgrade: solo consensus network upgrade –upgrade-version

17 - SOLO-5017

MultipleDeploymentsFoundSoloError

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

1. List existing deployments: solo deployment config list
2. Specify the deployment explicitly: solo node –deployment

18 - SOLO-5018

GrpcProxyEndpointFailedSoloError

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

1. Check node update transaction logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify gRPC endpoints are reachable: kubectl get svc -n
3. Retry the node update: solo consensus node update

19 - SOLO-5019

ExplorerPodNotFoundSoloError

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

1. Check pod status: kubectl get pods -A | grep explorer
2. Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/component=hiero-explorer
3. Check recent namespace events: kubectl get events -n –sort-by=.lastTimestamp

20 - SOLO-5020

ExplorerNotInRemoteConfigSoloError

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

1. List components in remote config: solo deployment config info
2. Deploy the explorer first: solo explorer deploy

21 - SOLO-5021

RelayPodNotFoundSoloError

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

1. Check pod status: kubectl get pods -A | grep relay
2. Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/instance=relay-
3. Check recent namespace events: kubectl get events -n –sort-by=.lastTimestamp

22 - SOLO-5022

RelayNotInRemoteConfigSoloError

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

1. List components in remote config: solo deployment config info
2. Deploy the relay first: solo relay deploy

23 - SOLO-5023

MirrorNodePodsNotFoundSoloError

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

1. Check pod status: kubectl get pods -n | grep
2. Inspect Helm release: helm status -n

24 - SOLO-5024

MirrorIngressControllerPodNotFoundSoloError

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

1. Check ingress controller pod status: kubectl get pods -A | grep ingress
2. Describe pods to check for crashes or evictions: kubectl describe pods -A -l app.kubernetes.io/name=haproxy-ingress
3. Check recent namespace events: kubectl get events -n –sort-by=.lastTimestamp

25 - SOLO-5025

MirrorNodeNotInRemoteConfigSoloError

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

1. List components in remote config: solo deployment config info
2. Deploy the mirror node first: solo mirror node add –deployment

26 - SOLO-5026

ClusterNotFoundInRemoteConfigSoloError

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

1. List configured cluster references: solo cluster-ref list
2. Inspect the remote config to see which clusters block nodes reference: kubectl get configmap solo-remote-config -n -o yaml
3. If the cluster was renamed or removed, the deployment config may need to be repaired

27 - SOLO-5027

GitHubApiRequestFailedError

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

1. Check network connectivity and GitHub availability, then retry. If the issue persists, confirm proxy/firewall settings.

28 - SOLO-5028

GitHubApiHttpResponseError

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

1. Verify GitHub API accessibility and credentials/rate limits, then retry.

29 - SOLO-5029

GitHubApiResponseParseFailedError

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

1. Inspect the GitHub API response shape and endpoint contract.

30 - SOLO-5030

GitHubApiResponseMissingTagNameError

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

1. Confirm the repository has a latest release and that the GitHub API response contains expected release fields.

31 - SOLO-5031

BlockNodePodNotFoundSoloError

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

1. Check pod status: kubectl get pods -A -l block-node.hiero.com/type=block-node
2. Describe pods to check for crashes or evictions: kubectl describe pods -A -l block-node.hiero.com/type=block-node
3. Check recent namespace events: kubectl get events -n –sort-by=.lastTimestamp

32 - SOLO-5032

BlockNodeNotReadySoloError

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

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

33 - SOLO-5033

BlockNodeNotInRemoteConfigSoloError

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

1. List all registered components: solo deployment config info
2. Verify you are targeting the correct deployment and namespace
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

34 - SOLO-5034

ExternalBlockNodeNotInRemoteConfigSoloError

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

1. Register the external block node first: solo block node add-external
2. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

35 - SOLO-5035

HelmRepoSetupFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List configured Helm repositories: helm repo list
3. Verify network connectivity to chart repository URLs
4. Update Helm repositories: helm repo update

36 - SOLO-5036

HelmRepoCheckFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. List configured Helm repositories: helm repo list
3. Verify network connectivity to chart repository URLs
4. Update Helm repositories: helm repo update

37 - SOLO-5037

HelmChartListFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes connectivity: kubectl cluster-info
3. List Helm releases manually: helm list -A

38 - SOLO-5038

HelmChartGenericInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect the Helm release: helm status -n
3. Check Helm release history: helm history -n
4. Inspect failing pods: kubectl get pods -A

39 - SOLO-5039

HelmChartUninstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Check if the release still exists: helm list -n
3. Inspect the release status: helm status -n
4. Check remaining pods: kubectl get pods -A

40 - SOLO-5040

HelmChartUpgradeFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect the release status: helm status -n
3. Review upgrade history: helm history -n
4. Check failing pods: kubectl get pods -A

41 - SOLO-5041

FileNotFoundSoloError

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

1. Verify the file exists at:
2. Check the path is correct and the file has not been deleted

42 - SOLO-5042

FileCopyFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the source file exists and is readable
3. Check that the destination directory exists and is writable
4. Verify sufficient disk space is available

43 - SOLO-5043

FileEmptySoloError

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

1. Verify the file contains valid content:
2. The file must not be empty to be processed

44 - SOLO-5044

FileInvalidJsonSoloError

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

1. Verify the file at contains valid JSON
2. Check for syntax errors such as missing commas, brackets, or quotes

45 - SOLO-5045

DirectoryCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the parent directory exists and is writable
3. Check available disk space

46 - SOLO-5046

ArchiveUnzipFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the archive is a valid zip file:
3. Ensure the archive is not corrupted
4. Check available disk space in the destination

47 - SOLO-5047

ArchiveTarFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the source path exists and is readable:
3. Check available disk space for the output archive

48 - SOLO-5048

ArchiveUntarFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the archive is a valid tar file:
3. Check the archive is not corrupted
4. Verify available disk space in the extraction destination

49 - SOLO-5049

DependencyVersionCheckFailedSoloError

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

1. Verify is installed and available in your PATH
2. Check the installation: which
3. Run solo init to install missing dependencies: solo init

50 - SOLO-5050

DependencyNotFoundSoloError

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

1. Install the missing dependency:
2. Run solo init to install all required dependencies: solo init
3. Verify the dependency is in your PATH: which

51 - SOLO-5051

DependencyManagerNotFoundSoloError

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

1. This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues

52 - SOLO-5052

DependencyInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify network connectivity for downloading the dependency
3. Check available disk space
4. Re-run initialization: solo init

53 - SOLO-5053

DependencyInstallDirectoryConflictSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Configure separate installation and temporary directories in your Solo configuration

54 - SOLO-5054

GitHubReleasesNotFoundSoloError

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

1. Verify network connectivity and GitHub availability
2. Check if GitHub API rate limits have been exceeded
3. Verify proxy or firewall settings allow access to api.github.com

55 - SOLO-5055

GitHubReleaseTagNotFoundSoloError

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

1. Verify the release tag ‘’ exists in the GitHub repository
2. Check the GitHub releases page for available versions
3. Verify network connectivity to api.github.com

56 - SOLO-5056

GitHubReleaseAssetNotFoundSoloError

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

1. Verify a release asset is available for your platform () and architecture ()
2. Check the GitHub releases page for supported platforms
3. Consider installing the dependency manually

57 - SOLO-5057

HomebrewInstallFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify network connectivity
3. Install Homebrew manually from https://brew.sh
4. Re-run initialization after installing Homebrew: solo init

58 - SOLO-5058

PodmanMachineInspectFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Podman is installed: podman –version
3. List Podman machines: podman machine list
4. Start the Podman machine if it is not running: podman machine start

59 - SOLO-5059

DockerAuthStaleSoloError

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

1. Re-authenticate with the GitHub Container Registry: docker login ghcr.io
2. Verify your GitHub Personal Access Token has the read:packages scope
3. Clear stale credentials: docker logout ghcr.io

60 - SOLO-5060

PvcCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify available storage in the cluster: kubectl get pv
3. Check if a StorageClass is configured: kubectl get storageclass
4. Inspect PVC events: kubectl describe pvc -n

61 - SOLO-5061

KubernetesApiInvalidResponseSoloError

Description

Thrown when the Kubernetes API returns an incorrect or unexpected response. 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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes API server is reachable: kubectl cluster-info
3. Check kubeconfig context: kubectl config current-context
4. Inspect Kubernetes API server health

62 - SOLO-5062

IngressClassListFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify Kubernetes connectivity: kubectl cluster-info
3. List IngressClasses manually: kubectl get ingressclass
4. Ensure the Kubernetes API server supports IngressClass resources (requires v1.18+)

63 - SOLO-5063

MultipleItemsFoundSoloError

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

1. This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues

64 - SOLO-5064

PodCreationFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Inspect pod events: kubectl get events -n
3. Check resource quotas: kubectl describe namespace
4. Verify node resource availability: kubectl get nodes

65 - SOLO-5065

PackageDownloadFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify network connectivity
3. Check if proxy or firewall settings block access to the download URL
4. Verify the download URL is accessible

66 - SOLO-5066

ChecksumReadFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the checksum file exists and is readable:
3. Re-download the package to regenerate the checksum file

67 - SOLO-5067

ContainerInvalidPathSoloError

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

1. This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues

68 - SOLO-5068

ContainerOperationFailedSoloError

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

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

69 - SOLO-5069

PostgresPodNotFoundSoloError

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

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

70 - SOLO-5070

InitSystemFilesFailedSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify write permissions for the Solo home directory (~/.solo)
3. Check available disk space
4. Re-run initialization: solo init

71 - SOLO-5071

CacheProviderNotConfiguredSoloError

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

1. This is an internal Solo error. File a bug report: https://github.com/hiero-ledger/solo/issues

72 - SOLO-5072

PodTerminationTimeoutSoloError

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

1. List pods still present: kubectl get pods -n -l <labels.join(’,’)>
2. Describe stuck pods for termination events: kubectl describe pod -n -l <labels.join(’,’)>
3. Check for finalizers blocking deletion: kubectl get pod -n -l <labels.join(’,’)> -o jsonpath=’{.items[*].metadata.finalizers}'
4. Force-delete stuck pods if safe: kubectl delete pod -n -l <labels.join(’,’)> –force –grace-period=0
5. Check solo logs for context: tail -n 100 ~/.solo/logs/solo.log

73 - SOLO-5073

ClusterRoleCheckFailedSoloError

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

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

74 - SOLO-9001

TimeoutSoloError

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

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the target resource or service is responding
3. Check Kubernetes pod status: kubectl get pods -A
4. Increase the timeout if the operation is expected to take longer