System on Solo

SOLO-5001

Mon, 01 Jan 0001 00:00:00 +0000

`ResourceNotFoundError`


Code	`SOLO-5001`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when an expected resource cannot be found; the message names the resource and, when available, wraps the underlying cause. solo looks up Kubernetes and related resources by name as it works, so this means the resource was absent where it was expected — for example it was not yet created, was deleted, or was searched for in the wrong place.

SOLO-5002

Mon, 01 Jan 0001 00:00:00 +0000

`ClusterConnectionFailedError`


Code	`SOLO-5002`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot establish a connection to the Kubernetes API server for a cluster reference; the message names the cluster reference and the kubeconfig context it tried. solo resolves the context from kubeconfig and connects before running any cluster operation, so this fires when that handshake fails: the context names a server that is unreachable or no longer exists, the cluster has not been started yet (for example a Kind cluster that was never created or was deleted), credentials have expired, or a transient network/DNS problem interrupted the call. It is retryable because a cluster that is still coming up, or a brief network blip, often resolves on a later attempt.

SOLO-5003

Mon, 01 Jan 0001 00:00:00 +0000

`PortForwardRefreshFailedError`


Code	`SOLO-5003`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot refresh its port-forwards; when available the underlying failure is wrapped in cause. solo periodically re-establishes port-forwards so endpoints stay reachable, so this means that refresh failed — for example a target pod was unavailable or the API connection dropped. It is retryable.

Troubleshooting Steps

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

SOLO-5004

Mon, 01 Jan 0001 00:00:00 +0000

`PortForwardStatusFailedError`


Code	`SOLO-5004`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot display port-forward status; when available the underlying failure is wrapped in cause. solo reads the state of active port-forwards to report it, so this means that status query failed — for example the cluster API was unreachable. It is retryable.

Troubleshooting Steps

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

SOLO-5005

Mon, 01 Jan 0001 00:00:00 +0000

`NamespaceNotFoundSoloError`


Code	`SOLO-5005`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a referenced Kubernetes namespace does not exist; the message names the namespace. solo operates within a deployment namespace, so this means the namespace is absent — for example it was never created, was deleted, or the wrong name was supplied.

Troubleshooting Steps

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

SOLO-5006

Mon, 01 Jan 0001 00:00:00 +0000

`PodNotFoundSoloError`


Code	`SOLO-5006`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo queries Kubernetes for the pod backing a consensus node alias and the lookup returns no pod; the message names the alias. solo needs the pod to run commands, copy files, or check status on a node, so this fires when no pod matches the expected labels in the namespace. Because pod scheduling is asynchronous, it can appear briefly during startup before the pod exists, which is why it is retryable; if it persists, the pod failed to schedule or start, was evicted, or the node was never deployed. This is the base error for the component-specific variants (explorer, relay, mirror-node, block-node, and Postgres pod-not-found errors).

SOLO-5007

Mon, 01 Jan 0001 00:00:00 +0000

`HaproxyPodsNotFoundSoloError`


Code	`SOLO-5007`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot find any HAProxy pods. solo relies on HAProxy pods to route traffic to consensus nodes, so this is raised when none are present in the namespace. It is retryable because the pods may still be scheduling; if it persists, HAProxy failed to start or was not deployed.

Troubleshooting Steps

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

SOLO-5008

Mon, 01 Jan 0001 00:00:00 +0000

`LoadBalancerNotFoundSoloError`


Code	`SOLO-5008`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot find the expected load balancer. solo looks up the load balancer that exposes a service externally, so this is raised when none is present yet. It is retryable because the load balancer may still be provisioning (for example waiting on MetalLB or a cloud provider); a persistent failure points to a networking misconfiguration.

SOLO-5009

Mon, 01 Jan 0001 00:00:00 +0000

`KubeContextNotFoundSoloError`


Code	`SOLO-5009`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when solo cannot determine the Kubernetes context for a node; the message names the node alias. By this point the node context should already be resolvable from configuration, so reaching it indicates an internal inconsistency and is treated as an internal Solo error.

Troubleshooting Steps

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

SOLO-5010

Mon, 01 Jan 0001 00:00:00 +0000

`ConsensusNodeNotInConfigSoloError`


Code	`SOLO-5010`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when solo looks up a consensus node by alias but it is not present in the configuration; the message names the alias. By this point the node should already be known, so reaching it indicates an internal inconsistency between the requested alias and the loaded configuration, and is treated as an internal Solo error.

SOLO-5011

Mon, 01 Jan 0001 00:00:00 +0000

`K8sSecretCreateFailedSoloError`


Code	`SOLO-5011`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot create a Kubernetes secret; the message describes the secret and, when available, wraps the underlying cause. solo stores keys and credentials as cluster secrets, so this means the secret could not be created — for example the namespace is missing, the API rejected the request, or a transient API error occurred. It is retryable.

SOLO-5012

Mon, 01 Jan 0001 00:00:00 +0000

`StatesDirectoryNotFoundSoloError`


Code	`SOLO-5012`
Category	System
Ownership	User
Retryable	No

Description

Thrown when the states directory for a node does not exist; the message names the node alias and the expected directory. solo reads saved consensus state from this directory, so this means it is missing or the path is wrong — for example no state was exported for the node, or the wrong path was supplied.

SOLO-5013

Mon, 01 Jan 0001 00:00:00 +0000

`PortForwardMissingSoloError`


Code	`SOLO-5013`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a configured port-forward is not present; the message names the component, its id, and the local-to-pod port mapping. solo expects each configured port-forward to be active so the component is reachable, so this means it is missing — for example it was never established or was dropped. It is retryable, since re-establishing the port-forward often succeeds.

SOLO-5014

Mon, 01 Jan 0001 00:00:00 +0000

`NoPvcFoundSoloError`


Code	`SOLO-5014`
Category	System
Ownership	User
Retryable	No

Description

Thrown when no PersistentVolumeClaims are found in a namespace where they were expected; the message names the namespace. Some operations require PVCs that are created only when persistent storage is enabled at deployment, so this means PVCs were not enabled for the network — redeploy with PVCs enabled.

Troubleshooting Steps

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

SOLO-5015

Mon, 01 Jan 0001 00:00:00 +0000

`ClusterReferenceUndeterminedSoloError`


Code	`SOLO-5015`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown during initialization when solo cannot determine which cluster reference to use. solo expects the active cluster reference to be resolvable at this point, so reaching this indicates an internal initialization or ordering defect rather than user input, and is treated as an internal Solo error.

Troubleshooting Steps

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

SOLO-5016

Mon, 01 Jan 0001 00:00:00 +0000

`UpgradeVersionFetchFailedSoloError`


Code	`SOLO-5016`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot fetch a requested upgrade version; the message names the version and wraps the underlying failure in cause. solo downloads upgrade artifacts for the chosen version, so this means the fetch did not complete — for example the version assets were unreachable or the download errored. It is retryable, since transient network issues often clear on a later attempt.

SOLO-5017

Mon, 01 Jan 0001 00:00:00 +0000

`MultipleDeploymentsFoundSoloError`


Code	`SOLO-5017`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a command needs a single deployment but several are configured and none was selected; the message names the source (local or remote) and the deployments found. solo cannot guess which one to use, so it asks you to disambiguate with --deployment.

Troubleshooting Steps

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

SOLO-5018

Mon, 01 Jan 0001 00:00:00 +0000

`GrpcProxyEndpointFailedSoloError`


Code	`SOLO-5018`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot set the gRPC Web proxy endpoint. solo configures this endpoint so gRPC Web clients can reach the network, so this means that configuration step failed — for example the target service or port-forward was not reachable. It is retryable, since a transient connectivity issue often clears on a later attempt.

SOLO-5019

Mon, 01 Jan 0001 00:00:00 +0000

`ExplorerPodNotFoundSoloError`


Code	`SOLO-5019`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot find a Hiero Explorer pod. solo locates the explorer pod to operate on it or check its status, so this is raised when no matching pod exists in the namespace — for example the explorer failed to start, was removed, or was never deployed.

Troubleshooting Steps

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

SOLO-5020

Mon, 01 Jan 0001 00:00:00 +0000

`ExplorerNotInRemoteConfigSoloError`


Code	`SOLO-5020`
Category	System
Ownership	User
Retryable	No

Description

Thrown when no Hiero Explorer component is present in the deployment remote configuration. solo looks the explorer up in the remote config before acting on it, so this means none is recorded — typically because the explorer was never deployed for this deployment, or was already removed.

Troubleshooting Steps

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

SOLO-5021

Mon, 01 Jan 0001 00:00:00 +0000

`RelayPodNotFoundSoloError`


Code	`SOLO-5021`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot find a JSON-RPC relay pod. solo locates the relay pod to operate on it or check status, so this is raised when no matching pod exists in the namespace — for example the relay failed to start, was removed, or was never deployed.

Troubleshooting Steps

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

SOLO-5022

Mon, 01 Jan 0001 00:00:00 +0000

`RelayNotInRemoteConfigSoloError`


Code	`SOLO-5022`
Category	System
Ownership	User
Retryable	No

Description

Thrown when no JSON-RPC relay is present in the deployment remote configuration. solo looks the relay up in the remote config before acting on it, so this means none is recorded — typically because it was never deployed for this deployment, or was already removed.

Troubleshooting Steps

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

SOLO-5023

Mon, 01 Jan 0001 00:00:00 +0000

`MirrorNodePodsNotFoundSoloError`


Code	`SOLO-5023`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot find any deployed mirror-node pods; the message names the release and namespace. solo locates the mirror node pods to operate on them, so this is raised when none match in the namespace — for example the release failed to deploy, was removed, or the wrong release or namespace was targeted.

SOLO-5024

Mon, 01 Jan 0001 00:00:00 +0000

`MirrorIngressControllerPodNotFoundSoloError`


Code	`SOLO-5024`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot find the mirror ingress controller pod. solo locates this pod to manage ingress for the mirror node, so this is raised when no matching pod exists in the namespace — for example it failed to start or was not deployed.

Troubleshooting Steps

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

SOLO-5025

Mon, 01 Jan 0001 00:00:00 +0000

`MirrorNodeNotInRemoteConfigSoloError`


Code	`SOLO-5025`
Category	System
Ownership	User
Retryable	No

Description

Thrown when no mirror node is present in the deployment remote configuration. solo looks the mirror node up in the remote config before acting on it, so this means none is recorded — typically because it was never deployed for this deployment, or was already removed.

Troubleshooting Steps

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

SOLO-5026

Mon, 01 Jan 0001 00:00:00 +0000

`ClusterNotFoundInRemoteConfigSoloError`


Code	`SOLO-5026`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a referenced cluster is not present in the deployment remote configuration; the message names the cluster reference. solo expects the cluster to be recorded in the remote config before acting on it, so this means the reference does not match any recorded cluster — typically a misspelled name or a cluster that was never attached to the deployment.

SOLO-5027

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubApiRequestFailedError`


Code	`SOLO-5027`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a GitHub API request cannot be completed; the message names the URL and wraps the underlying failure in cause. The request did not produce a usable HTTP response at all — for example a network or DNS failure, or a dropped connection. It is retryable, since transient network problems often clear on a later attempt.

SOLO-5028

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubApiHttpResponseError`


Code	`SOLO-5028`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a GitHub API request returns a non-success HTTP status; the message names the URL and the status code. solo calls the GitHub API to discover releases and download assets, so this means GitHub responded with an error status — for example rate limiting, a missing resource, or a server error. It is retryable, since transient statuses such as rate limits often clear on a later attempt.

SOLO-5029

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubApiResponseParseFailedError`


Code	`SOLO-5029`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot parse a GitHub API response; the message names the URL and wraps the underlying failure in cause. solo parses release metadata from the API, so this means the body could not be parsed — for example it was not valid JSON or did not match the expected structure.

Troubleshooting Steps

Inspect the GitHub API response shape and endpoint contract.

SOLO-5030

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubApiResponseMissingTagNameError`


Code	`SOLO-5030`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when a GitHub API response is missing the expected tag_name field; the message names the URL. solo reads tag_name to identify a release version, so this means the response came back without it — indicating an unexpected response shape from the API.

Troubleshooting Steps

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

SOLO-5031

Mon, 01 Jan 0001 00:00:00 +0000

`BlockNodePodNotFoundSoloError`


Code	`SOLO-5031`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot find a running block node pod. solo locates the block node pod to run commands or check its status, so this is raised when no matching pod exists in the namespace. It is retryable because pod scheduling is asynchronous and the pod may appear shortly; if it persists, the block node failed to start or was never deployed.

SOLO-5032

Mon, 01 Jan 0001 00:00:00 +0000

`BlockNodeNotReadySoloError`


Code	`SOLO-5032`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a deployed block node does not become ready; the message names the release and wraps the underlying failure in cause. solo waits for the block node pods to reach a Ready state, so this means that wait did not succeed. It is retryable, since a block node that is merely slow to start often becomes ready on a later attempt; a persistent failure points to a crash-looping or misconfigured block node.

SOLO-5033

Mon, 01 Jan 0001 00:00:00 +0000

`BlockNodeNotInRemoteConfigSoloError`


Code	`SOLO-5033`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a referenced block node is not present in the deployment remote configuration; when provided, the message includes its identifier. solo looks components up in the remote config before acting on them, so this means the block node id does not match any recorded component — typically because it was never added, was already removed, or the wrong id was supplied.

SOLO-5034

Mon, 01 Jan 0001 00:00:00 +0000

`ExternalBlockNodeNotInRemoteConfigSoloError`


Code	`SOLO-5034`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a referenced external block node is not present in the deployment remote configuration; when provided, the message includes its id. solo looks external block nodes up in the remote config before acting on them, so this means the id does not match any recorded external block node — typically because it was never added or the wrong id was supplied.

SOLO-5035

Mon, 01 Jan 0001 00:00:00 +0000

`HelmRepoSetupFailedSoloError`


Code	`SOLO-5035`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot set up the Helm chart repositories; the underlying failure is wrapped in cause. solo adds and updates the repositories its charts come from, so this means that setup failed — for example a repository URL was unreachable or the Helm CLI errored.

Troubleshooting Steps

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

SOLO-5036

Mon, 01 Jan 0001 00:00:00 +0000

`HelmRepoCheckFailedSoloError`


Code	`SOLO-5036`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot check the configured Helm chart repositories; the underlying failure is wrapped in cause. solo verifies repositories before installing charts from them, so this means that check failed — for example the Helm CLI errored or a repository was unreachable.

Troubleshooting Steps

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

SOLO-5037

Mon, 01 Jan 0001 00:00:00 +0000

`HelmChartListFailedSoloError`


Code	`SOLO-5037`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot list installed Helm charts; the underlying failure is wrapped in cause. solo lists releases to check what is installed, so this means the helm list failed — for example the Helm CLI errored or the cluster API was unreachable.

Troubleshooting Steps

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

SOLO-5038

Mon, 01 Jan 0001 00:00:00 +0000

`HelmChartGenericInstallFailedSoloError`


Code	`SOLO-5038`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot install a Helm chart release; the message names the release and wraps the underlying failure in cause. This is the generic install failure used by the Helm client, so it means the helm install did not succeed — for example a bad chart version or values, an image that cannot be pulled, or a cluster that is unreachable or short on resources.

SOLO-5039

Mon, 01 Jan 0001 00:00:00 +0000

`HelmChartUninstallFailedSoloError`


Code	`SOLO-5039`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot uninstall a Helm chart release; the message names the release and wraps the underlying failure in cause. solo uninstalls releases during teardown, so this means the helm uninstall did not complete — for example the release was not found, a resource could not be deleted, or the cluster API was unreachable.

SOLO-5040

Mon, 01 Jan 0001 00:00:00 +0000

`HelmChartUpgradeFailedSoloError`


Code	`SOLO-5040`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot upgrade a Helm chart release; the message names the release and wraps the underlying failure in cause. solo upgrades releases to change chart version or values, so this means the helm upgrade did not succeed — for example a bad chart or values, an image that cannot be pulled, or a cluster issue.

SOLO-5041

Mon, 01 Jan 0001 00:00:00 +0000

`FileNotFoundSoloError`


Code	`SOLO-5041`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a file solo was asked to use does not exist; the message names the path. solo reads files from paths provided on the command line or in configuration, so this means the file is missing or the path is wrong — for example a typo or a file that was moved or deleted.

SOLO-5042

Mon, 01 Jan 0001 00:00:00 +0000

`FileCopyFailedSoloError`


Code	`SOLO-5042`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when a file copy operation fails; the underlying failure is wrapped in cause. solo copies files between local paths and pods during setup, so this means the copy did not complete — for example the source was unreadable, the destination was not writable, or the connection dropped.

Troubleshooting Steps

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

SOLO-5043

Mon, 01 Jan 0001 00:00:00 +0000

`FileEmptySoloError`


Code	`SOLO-5043`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a file solo was asked to read is empty; the message names the path. solo expects the referenced file to contain data, so this means it exists but has no content — for example the wrong file was supplied or it was not fully written.

Troubleshooting Steps

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

SOLO-5044

Mon, 01 Jan 0001 00:00:00 +0000

`FileInvalidJsonSoloError`


Code	`SOLO-5044`
Category	System
Ownership	User
Retryable	No

Description

Thrown when a file solo was asked to parse does not contain valid JSON; the message names the path. solo parses JSON from user-provided files, so this means the content could not be parsed — for example a syntax error, a truncated file, or a non-JSON file supplied.

Troubleshooting Steps

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

SOLO-5045

Mon, 01 Jan 0001 00:00:00 +0000

`DirectoryCreationFailedSoloError`


Code	`SOLO-5045`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot create a directory; the underlying failure is wrapped in cause. solo creates working and output directories as it runs, so this means the directory could not be created — for example missing permissions, a read-only or full disk, or a conflicting existing path.

Troubleshooting Steps

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

SOLO-5046

Mon, 01 Jan 0001 00:00:00 +0000

`ArchiveUnzipFailedSoloError`


Code	`SOLO-5046`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot unzip an archive; the message names the source and wraps the underlying failure in cause. solo unzips downloaded packages and state archives, so this means the unzip failed — for example the zip is corrupt or truncated, a wrong password was supplied, or the destination could not be written.

Troubleshooting Steps

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

SOLO-5047

Mon, 01 Jan 0001 00:00:00 +0000

`ArchiveTarFailedSoloError`


Code	`SOLO-5047`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot create a tar archive from a source path; the message names the source and wraps the underlying failure in cause. solo packages directories into tar archives (for example to bundle state or logs), so this means the archiving step failed — for example the source path was unreadable, a file changed during archiving, or the destination could not be written.

SOLO-5048

Mon, 01 Jan 0001 00:00:00 +0000

`ArchiveUntarFailedSoloError`


Code	`SOLO-5048`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot extract a tar archive; the message names the archive and wraps the underlying failure in cause. solo unpacks tar archives it downloads or restores, so this means extraction failed — for example the archive is corrupt or truncated, or the destination directory could not be written.

Troubleshooting Steps

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

SOLO-5049

Mon, 01 Jan 0001 00:00:00 +0000

`DependencyVersionCheckFailedSoloError`


Code	`SOLO-5049`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot determine the installed version of a dependency; the message names the dependency and, when present, wraps the underlying cause (otherwise it notes the tool may not be installed or on PATH). solo checks tool versions to confirm they meet its requirements, so this means the version check could not run or its output could not be parsed.

SOLO-5050

Mon, 01 Jan 0001 00:00:00 +0000

`DependencyNotFoundSoloError`


Code	`SOLO-5050`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when a required dependency is not found; the message names it. solo expects certain external tools to be available, so this means the dependency could not be located — for example it is not installed or not on PATH.

Troubleshooting Steps

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

SOLO-5051

Mon, 01 Jan 0001 00:00:00 +0000

`DependencyManagerNotFoundSoloError`


Code	`SOLO-5051`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when no dependency manager is registered for a requested dependency; the message names the dependency. solo routes each managed dependency to a registered manager that knows how to install and verify it, so a missing registration points to an internal wiring defect and is treated as an internal Solo error.

Troubleshooting Steps

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

SOLO-5052

Mon, 01 Jan 0001 00:00:00 +0000

`DependencyInstallFailedSoloError`


Code	`SOLO-5052`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot install a managed dependency; the message names the executable and wraps the underlying failure in cause. solo installs tools like kubectl, helm, and kind when they are missing, so this means installation failed — for example the download failed, the archive was invalid, or the target directory was not writable.

SOLO-5053

Mon, 01 Jan 0001 00:00:00 +0000

`DependencyInstallDirectoryConflictSoloError`


Code	`SOLO-5053`
Category	System
Ownership	User
Retryable	No

Description

Thrown when the chosen installation directory is the same as the temporary directory used during install. solo installs managed dependencies (such as kubectl, helm, kind) into a target directory distinct from its temp workspace, so this means the configured paths collide — choose a different installation directory.

Troubleshooting Steps

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

SOLO-5054

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubReleasesNotFoundSoloError`


Code	`SOLO-5054`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a GitHub repository reports no releases. solo lists releases to choose a version to download, so this means the repository returned an empty release list. It is retryable, since a transient API issue can return empty results that resolve on a later attempt.

Troubleshooting Steps

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

SOLO-5055

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubReleaseTagNotFoundSoloError`


Code	`SOLO-5055`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when no GitHub release exists for a requested tag; the message names the tag. solo looks up releases by tag to download a specific version, so this means that tag has no release — for example a wrong or not-yet-published version.

Troubleshooting Steps

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

SOLO-5056

Mon, 01 Jan 0001 00:00:00 +0000

`GitHubReleaseAssetNotFoundSoloError`


Code	`SOLO-5056`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when no GitHub release asset matches the running platform and architecture; the message names the platform and arch. solo selects the release asset built for the current OS and CPU, so this means the release exists but has no matching asset — for example the platform or architecture is unsupported by that release.

SOLO-5057

Mon, 01 Jan 0001 00:00:00 +0000

`HomebrewInstallFailedSoloError`


Code	`SOLO-5057`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot install Homebrew. On macOS solo may use Homebrew to install some dependencies, so this means the Homebrew installation did not succeed — for example the install script failed or could not be downloaded.

Troubleshooting Steps

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

SOLO-5058

Mon, 01 Jan 0001 00:00:00 +0000

`PodmanMachineInspectFailedSoloError`


Code	`SOLO-5058`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot inspect the Podman machine; the underlying failure is wrapped in cause. When using Podman, solo inspects the machine to read its configuration, so this means that inspection failed — for example Podman is not installed, the machine is not running, or the command errored.

Troubleshooting Steps

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

SOLO-5059

Mon, 01 Jan 0001 00:00:00 +0000

`DockerAuthStaleSoloError`


Code	`SOLO-5059`
Category	System
Ownership	User
Retryable	No

Description

Thrown when solo detects stale Docker authentication for the GitHub Container Registry (GHCR). solo needs valid GHCR credentials to pull images, so this means the cached Docker auth is expired or invalid — re-authenticate to GHCR to refresh it.

Troubleshooting Steps

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

SOLO-5060

Mon, 01 Jan 0001 00:00:00 +0000

`PvcCreationFailedSoloError`


Code	`SOLO-5060`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot create a PersistentVolumeClaim. solo provisions PVCs for components that need persistent storage, so this means the create request failed — for example the API rejected the spec, or no StorageClass could satisfy it.

Troubleshooting Steps

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

SOLO-5061

Mon, 01 Jan 0001 00:00:00 +0000

`KubernetesApiInvalidResponseSoloError`


Code	`SOLO-5061`
Category	System
Ownership	Infrastructure
Retryable	No

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

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

SOLO-5062

Mon, 01 Jan 0001 00:00:00 +0000

`IngressClassListFailedSoloError`


Code	`SOLO-5062`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot list Kubernetes IngressClasses; the underlying failure is wrapped in cause. solo reads IngressClasses to configure ingress for components, so this means the lookup failed — for example the cluster API was unreachable or the current user lacks permission.

Troubleshooting Steps

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

SOLO-5063

Mon, 01 Jan 0001 00:00:00 +0000

`MultipleItemsFoundSoloError`


Code	`SOLO-5063`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when a Kubernetes lookup that expected a single resource matches more than one; the filters used are attached to the error. solo expects these filtered lookups to be unique, so multiple matches indicate an internal assumption was violated (for example over-broad filters), and it is treated as an internal Solo error.

Troubleshooting Steps

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

SOLO-5064

Mon, 01 Jan 0001 00:00:00 +0000

`PodCreationFailedSoloError`


Code	`SOLO-5064`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot create a Kubernetes pod. solo creates helper or workload pods as part of its operations, so this means the create request did not yield a running pod — for example the API rejected the spec, scheduling failed, or required resources were unavailable.

Troubleshooting Steps

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

SOLO-5065

Mon, 01 Jan 0001 00:00:00 +0000

`PackageDownloadFailedSoloError`


Code	`SOLO-5065`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when solo cannot download a package; the message names the URL and wraps the underlying failure in cause. solo downloads packages such as platform builds and tools, so this means the download did not complete — for example the URL was unreachable, returned an error, or the connection dropped. It is retryable, since transient network issues often clear on a later attempt.

SOLO-5066

Mon, 01 Jan 0001 00:00:00 +0000

`ChecksumReadFailedSoloError`


Code	`SOLO-5066`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot read a checksum file; the message names the file. solo reads checksum files to verify downloaded artifacts, so this means the file could not be read — for example it is missing, empty, or unreadable due to permissions or an interrupted download.

Troubleshooting Steps

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

SOLO-5067

Mon, 01 Jan 0001 00:00:00 +0000

`ContainerInvalidPathSoloError`


Code	`SOLO-5067`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when solo is given an invalid path for a container operation; the message names the context and the path. solo validates container paths before using them for copy or exec operations, so an invalid value here (for example an empty or malformed path passed internally) points to a defect in the calling code and is treated as an internal Solo error.

SOLO-5068

Mon, 01 Jan 0001 00:00:00 +0000

`ContainerOperationFailedSoloError`


Code	`SOLO-5068`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when an operation against a container fails; the message names the operation and wraps the underlying failure in cause. solo runs operations such as exec and file copy inside pod containers, so this means that operation failed — for example the container was not reachable, the command errored, or the connection dropped.

Troubleshooting Steps

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

SOLO-5069

Mon, 01 Jan 0001 00:00:00 +0000

`PostgresPodNotFoundSoloError`


Code	`SOLO-5069`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot find the Postgres pod; the message names the namespace. solo locates the mirror node Postgres pod to operate on the database, so this is raised when no matching pod exists in the namespace — for example the database failed to start or was not deployed.

Troubleshooting Steps

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

SOLO-5070

Mon, 01 Jan 0001 00:00:00 +0000

`InitSystemFilesFailedSoloError`


Code	`SOLO-5070`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot initialize its system files; the underlying failure is wrapped in cause. solo lays down the files it needs under its home directory during initialization, so this means that step failed — for example the directory was not writable or a file could not be created.

Troubleshooting Steps

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

SOLO-5071

Mon, 01 Jan 0001 00:00:00 +0000

`CacheProviderNotConfiguredSoloError`


Code	`SOLO-5071`
Category	System
Ownership	Solo
Retryable	No

Description

Thrown when a cache is built before its required provider or engine has been set; the message names the cache and which piece is missing. solo requires both to be configured before constructing the cache, so reaching this points to an internal setup or ordering defect rather than user input, and is treated as an internal Solo error.

SOLO-5072

Mon, 01 Jan 0001 00:00:00 +0000

`PodTerminationTimeoutSoloError`


Code	`SOLO-5072`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when pods do not terminate within the allotted time; the message names the namespace and the label selector being waited on. solo waits for matching pods to disappear during teardown, so this means they were still present when the deadline passed — for example a pod is stuck terminating or has a finalizer. It is retryable, since termination often completes shortly after.

SOLO-5073

Mon, 01 Jan 0001 00:00:00 +0000

`ClusterRoleCheckFailedSoloError`


Code	`SOLO-5073`
Category	System
Ownership	Infrastructure
Retryable	No

Description

Thrown when solo cannot check whether a Kubernetes ClusterRole exists; the message names the role and wraps the underlying failure in cause. solo queries for ClusterRoles before installing or relying on them, so this means the lookup failed — for example the Kubernetes API was unreachable or the current user lacks permission to read ClusterRoles.

SOLO-9001

Mon, 01 Jan 0001 00:00:00 +0000

`TimeoutSoloError`


Code	`SOLO-9001`
Category	System
Ownership	Infrastructure
Retryable	Yes

Description

Thrown when a bounded operation does not finish within the time solo allows for it. solo guards long-running waits with deadlines — most often while polling for a Kubernetes pod or service to become Ready, but also for Hedera SDK calls and other long-running CLI steps — and raises this once the deadline passes without the expected condition being met. It signals that the operation was still in progress (or stuck), not that it definitively failed, which is why it is retryable: a resource that is merely slow to stabilise often succeeds on a later run or with a larger timeout. It is the base error for more specific timeouts such as PodTerminationTimeoutSoloError and ClusterApiServerTimeoutSoloError.