System

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

1 - SOLO-2032

MinioOperatorCrdsOrphanedSoloError

Description

Thrown when the MinIO Operator’s cluster-scoped CRDs exist but no Helm release owns them. The CRDs outlive the namespace the operator was installed into, so deleting that namespace leaves them behind. Helm will not adopt resources another release created, so installing over them fails; and treating their presence as “already installed” would be worse — the operator would never run, and the Tenant resource created later would sit unreconciled with nothing pointing at the cause.

Troubleshooting Steps

1. Delete the leftover CRDs, then run the setup again: kubectl delete crd <crdNames.join(’ ‘)>
2. Deleting these CRDs also deletes any MinIO Tenant resources defined by them
3. They are usually left behind when the operator namespace was deleted directly rather than through solo cluster-ref config reset

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

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

4 - 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 port-forwards refresh –deployment

5 - 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 port-forwards refresh –deployment

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

7 - 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. A StatefulSet whose claim cannot be provisioned never creates its pod; check PVC/PV binding: kubectl get pvc,pv -n
4. Check the storage class and its provisioner: kubectl get storageclass
5. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

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

9 - 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
2. Ensure your cloud provider supports LoadBalancer services
3. Review cloud provisioning logs for LB assignment delays

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

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

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

13 - 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///

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

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

16 - 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. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

50 - 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. Re-run the command; solo installs the dependencies it manages automatically

51 - 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. Re-run the command; solo installs the dependencies it manages automatically
3. Verify the dependency is in your PATH: which

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

53 - 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 the command to retry the installation

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

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

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

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

58 - 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 the command after installing Homebrew

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

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

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

62 - SOLO-5061

KubernetesApiInvalidResponseSoloError

Description

Thrown when the Kubernetes API returns an incorrect or unexpected response; when the underlying failure is known it is named in the message and wrapped in cause. solo expects well-formed responses from the API, so this means a call returned something it could not interpret — for example a malformed or partial response, often indicating an API server problem.

Troubleshooting Steps

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

63 - 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+)

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

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

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

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

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

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

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

71 - 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 the command; solo sets up its system files at the start of every command

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

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

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

75 - SOLO-5074

UnsupportedLinuxDistributionSoloError

Description

Thrown when Solo cannot determine a supported native package manager for the current Linux distribution, so it cannot automatically install system dependencies (git, iptables, podman). Solo supports apt-get (Debian/Ubuntu), dnf (Fedora/RHEL), yum (RHEL 7/CentOS 7), zypper (openSUSE), pacman (Arch) and apk (Alpine).

Troubleshooting Steps

1. Install one of the supported package managers (apt-get, dnf, yum, zypper, pacman, apk), or
2. Install Solo and its dependencies (podman, git, iptables) manually, then re-run the command

76 - SOLO-5075

BlockNodesJsonEmptySoloError

Troubleshooting Steps

1. Ensure at least one block node is deployed: solo block-node deploy
2. Check the block node mapping flags: –block-node-mapping or –external-block-node-mapping
3. List all registered components: solo deployment config info
4. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

77 - SOLO-5076

HelmChartPullNoArchiveSoloError

Description

Thrown when helm pull completes without error but no new chart tarball appears in the cache charts directory; the message names the chart and version that were being cached. solo identifies the pulled archive by diffing the directory contents before and after the pull, so an empty diff means Helm reported success without producing the expected .tgz — for example due to an unexpected Helm CLI behaviour change or a filesystem issue in the cache directory.

Troubleshooting Steps

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the Helm CLI works: helm version
3. Try pulling the chart manually: helm pull –version

78 - SOLO-5077

PodmanRuntimeConfigurationFailedSoloError

Description

Thrown when the container runtime stack behind the Homebrew-installed podman on Linux cannot be configured or fails its post-configuration probe — for example the crun or conmon binary is missing from the Homebrew prefix, a network helper download failed, or podman rejects the generated configuration. Without this configuration podman would fall back to the host’s system container stack, which may be too old for it.

Troubleshooting Steps

1. Check solo logs: tail -n 100 ~/.solo/logs/solo.log
2. Verify the Homebrew podman installation: brew doctor && podman info
3. Inspect the generated configuration files under ~/.solo/config (containers.conf, registries.conf)
4. Reinstall the Homebrew podman stack if binaries are missing: brew reinstall podman

79 - SOLO-5078

ClusterUnreachableError

Description

Thrown when a Kubernetes API call against a remote cluster fails for any reason other than the resource being absent; the message names the kubeconfig context and the underlying failure, which is also wrapped in cause. solo reads and writes cluster state over the Kubernetes API for every deployment operation, so this means the call never produced a usable answer: the API server is down or unreachable over the network, the kubeconfig context points at a cluster that no longer exists, credentials have expired, or RBAC denied the request. Kind clusters are excluded — a local kind API failure is reported as a Kubernetes API invalid response instead. It is retryable because an API server that is restarting, or a transient network problem, often clears on a later attempt.

Troubleshooting Steps

1. Verify the cluster is reachable: kubectl cluster-info –context
2. Verify the kubeconfig context still exists: kubectl config get-contexts
3. Verify your credentials and RBAC permissions for the namespace
4. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

80 - SOLO-5079

KindClusterStoppedError

Description

Thrown when a kind cluster’s node container was found stopped, solo started it again, and the cluster’s Kubernetes API still did not answer; the last API failure is wrapped in cause. A kind node that restarts but never serves its API usually means the cluster did not survive whatever stopped it — the host was rebooted and the node’s networking or storage no longer lines up, the container is crash-looping, or the kubeconfig entry now points at a port the restarted node no longer listens on. It is retryable because a control plane can simply need longer than solo waited.

Troubleshooting Steps

1. Check the node container is running: docker ps -a –filter name=-control-plane
2. Inspect why the node is not serving its API: docker logs -control-plane
3. Verify the cluster answers: kubectl cluster-info –context kind-
4. Recreate the cluster if it did not survive being stopped: kind delete cluster –name

81 - SOLO-5080

ContainerEngineNotRunningError

Description

Thrown when solo needs the local container engine and neither Docker nor Podman answers; the failure that led solo to look is wrapped in cause. A local kind cluster only exists as containers on this machine, so with no engine running solo can neither reach the cluster nor tell whether it is still there. The usual reason is simply that Docker Desktop, the Docker daemon or the Podman machine is not started. solo does not start the engine itself, because doing so is platform-specific and needs privileges the CLI should not take on its own. It is retryable once the engine is up.

Troubleshooting Steps

1. Start Docker Desktop, or the Docker daemon: sudo systemctl start docker
2. If you use Podman, start its machine: podman machine start
3. Confirm the engine answers: docker info
4. Then re-run the command

82 - SOLO-5081

PodNotReadySoloError

Description

Thrown when a pod matching the expected labels was found but never reached the required phase or readiness condition before solo stopped waiting; the message names the pod, its last observed phase, and a per-container summary (readiness, restart count, and any waiting/terminated reason). This is distinct from the pod-not-found errors: the pod exists, but something is keeping it from becoming ready — most commonly a failing startup or readiness probe, a crash-looping container, or an unreachable dependency the container’s health check verifies. It is retryable because readiness is often only delayed; if it persists, inspect the pod rather than the scheduler.

Troubleshooting Steps

1. Describe the pod for probe failures and events: kubectl describe pod -n
2. Check container logs, including the previous run: kubectl logs -n –previous
3. If the readiness probe checks a dependency (e.g. a mirror node or database), verify that dependency is healthy
4. Check PVC/PV binding and volume attach events: kubectl get pvc -n ; kubectl describe pvc -n
5. Review solo logs: tail -n 100 ~/.solo/logs/solo.log

83 - SOLO-5082

PortForwardStopFailedError

Description

Thrown when solo cannot stop its port-forwards; when available the underlying failure is wrapped in cause. Stopping tears down the running kubectl port-forward processes and removes their configuration from the deployment’s remote config, so this means that teardown failed — for example a process could not be signalled or the remote config could not be persisted. It is retryable.

Troubleshooting Steps

1. Check the port-forwards of your deployment: solo deployment config ports –deployment
2. Check for lingering processes: ps aux | grep port-forward

84 - SOLO-5083

SoloLogsDirectoryNotWritableSoloError

Description

Thrown when solo cannot write to its log directory or to one of the log files inside it; the message names the offending path and the underlying failure is wrapped in cause. solo opens solo.ndjson and solo.log under its logs directory before running any command, so an unwritable path there stops every invocation — including solo --version, which otherwise touches nothing. The usual cause is a directory or log file left behind by an installation that ran as a different user, for example an earlier sudo npm install -g @hiero-ledger/solo, which leaves the files owned by root.

Troubleshooting Steps

1. Check who owns the path: ls -la ~/.solo ~/.solo/logs
2. Take ownership if it belongs to another user: sudo chown -R “$(id -u):$(id -g)” ~/.solo
3. Or delete the directory and let solo recreate it: rm -rf ~/.solo
4. Reinstall without sudo so no root-owned files are left behind: npm install -g @hiero-ledger/solo
5. Or point solo at a writable location instead: export SOLO_HOME=

85 - SOLO-5084

PvcMountVerificationFailedSoloError

Description

Thrown when PVC mount verification finds that a pod’s PersistentVolumeClaim mounts are not backed by the storage the claims requested, and verification was configured to fail rather than warn. Provisioners that hand out directories on an existing filesystem do not enforce the requested size, so this condition is invisible to Kubernetes: the claim binds, the pod runs, and the shortfall only surfaces later as a full disk. The usual cause is that the directory tree the provisioner writes into is not the mount point it was meant to be — a data array that failed to mount at boot leaves the path on the system disk instead.

Troubleshooting Steps

1. Check what the claims bound to and how large they really are: kubectl get pvc,pv -n
2. Identify the provisioner and the host directory it writes into: kubectl get storageclass -o yaml
3. On the node, confirm that directory is on the intended device and not the system disk: df -h ; lsblk; findmnt
4. If an intended data array or disk failed to mount at boot, mount it and redeploy so the claims are provisioned onto it
5. To deploy anyway and only warn, omit –verify-pvc-mounts

86 - SOLO-5085

SavedStateHashToolMissingSoloError

Description

Thrown when the consensus-node container has none of sha256sum, shasum, or openssl; the message names the pod. wait-for-stable-saved-state.sh fingerprints the saved-state directory with whichever of those is available to detect when background flushes stop changing disk contents, and this is permanent for a given image rather than something that resolves with more polling attempts, so solo fails fast instead of waiting out the full saved-state stability timeout.

Troubleshooting Steps

1. Use a consensus-node image that includes sha256sum, shasum, or openssl
2. Check the image in use: kubectl get pod -n -o jsonpath="{.spec.containers[*].image}"

87 - SOLO-5086

CacheManifestDownloadFailedSoloError

Description

Thrown when the image cache manifest cannot be downloaded from the Solo release assets; the message names the manifest URL. solo reads this manifest to learn which image archives to download, so this means the release has no manifest published or the network call failed — check connectivity and confirm the running Solo version has a published release.

Troubleshooting Steps

1. Confirm the machine can reach github.com
2. Confirm the running Solo version has a published release with a cache-manifest.json asset
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

88 - SOLO-5087

CacheManifestInvalidSoloError

Description

Thrown when the downloaded image cache manifest does not match the expected schema; the message names the manifest URL and what was wrong. solo refuses to act on a manifest it cannot fully validate because the entries drive downloads and hash checks, so this means the published artifact is malformed — report it.

Troubleshooting Steps

1. File a bug report with the manifest URL: https://github.com/hiero-ledger/solo/issues

89 - SOLO-5088

CacheArchiveHashMismatchSoloError

Description

Thrown when a cached image archive no longer matches the SHA-256 published for it (in the image cache manifest or its cached .sha256 file), checked again immediately before the archive is loaded into the cluster; the message names the image and the archive. solo refuses to load bytes it cannot vouch for, so this means the archive was corrupted or altered after it was downloaded — the archive has been deleted and solo cache image pull will download it again.

Troubleshooting Steps

1. Run solo cache image pull to download the archive again, then retry
2. The archive has already been deleted, so the next pull will not skip it
3. Check solo logs: tail -n 100 ~/.solo/logs/solo.log

90 - SOLO-5089

CachedFileInaccessibleSoloError

Description

Thrown when a file solo previously cached under SOLO_HOME can no longer be opened; the message names the path and the underlying failure is in cause. The cache is reused across deploys, so this means the file survived but its permissions no longer allow access — on Windows an empty DACL (which denies every principal, including the owner, and blocks deletion) and on POSIX a foreign owner or a cleared mode are the usual roots.

Troubleshooting Steps

1. This is a local cache problem, not a cluster problem; the cluster does not need to be recreated
2. On Windows, repair the permissions: icacls “” /reset
3. If that reports access denied, take ownership first: takeown /f “”
4. On macOS and Linux, check the owner and mode: ls -l
5. Then delete the file so solo re-creates it on the next run
6. To repair the whole cache on Windows: takeown /f “%USERPROFILE%.solo” /r /d y && icacls “%USERPROFILE%.solo” /reset /t /c /q

91 - SOLO-5091

BlockNodeBlocksUnavailableSoloError

Description

Thrown when a block node does not expose any block above the mirror importer’s last imported block within the wait window; the message names the block number and the wait duration. It is retryable, since the block node may simply still be starting after a restore; a persistent failure points to a consensus node that is not streaming blocks to the block node.

Troubleshooting Steps

1. Verify the consensus node is ACTIVE and streaming blocks to the block node
2. Check block node logs for the status heartbeat (newestBlock): kubectl logs -A -l app.kubernetes.io/name=block-node
3. Re-run: solo config ops bridge-import-gap

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