Deployment

• 1: SOLO-2001
• 2: SOLO-2002
• 3: SOLO-2003
• 4: SOLO-2004
• 5: SOLO-2005
• 6: SOLO-2006
• 7: SOLO-2007
• 8: SOLO-2008
• 9: SOLO-2009
• 10: SOLO-2010
• 11: SOLO-2011
• 12: SOLO-2012
• 13: SOLO-2013
• 14: SOLO-2014
• 15: SOLO-2015
• 16: SOLO-2016
• 17: SOLO-2017
• 18: SOLO-2018
• 19: SOLO-2019
• 20: SOLO-2020
• 21: SOLO-2021
• 22: SOLO-2022
• 23: SOLO-2023
• 24: SOLO-2024
• 25: SOLO-2025
• 26: SOLO-2026
• 27: SOLO-2027
• 28: SOLO-2028
• 29: SOLO-2029
• 30: SOLO-2030

1 - SOLO-2001

CreateDeploymentSoloError

Description

Thrown when solo deployment config create cannot record a new deployment; the underlying failure is wrapped in cause. Creating a deployment writes its entry to the local configuration and provisions the associated namespace, so this is raised when that work fails — for example the local config could not be written, or the Kubernetes API rejected or could not create the namespace. It is retryable because a transient cluster or filesystem issue often clears on a second attempt.

Troubleshooting Steps

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

2 - SOLO-2002

DeploymentAlreadyExistsSoloError

Description

Thrown when solo deployment config create is asked to create a deployment whose name is already present in the local configuration; the message names the conflicting deployment. Deployment names must be unique because solo keys each deployment’s namespace and cluster references by name, so it refuses to overwrite an existing entry. Choose a different name, or operate on the existing deployment instead of recreating it.

Troubleshooting Steps

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

3 - SOLO-2003

DeploymentNotFoundError

Description

Thrown when a command resolves a deployment by name but that name is not registered in the local configuration; the error message names the deployment that was requested. solo looks the deployment up to find its namespace and cluster references before acting, so the lookup fails when the --deployment value is misspelled, when the deployment was never created with solo deployment config create, or when it was removed by a prior delete. It can also surface after switching SOLO_HOME to a config that does not contain the deployment.

Troubleshooting Steps

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

4 - SOLO-2004

DeploymentHasRemoteResourcesError

Description

Thrown when a deployment is deleted while it still has live components running in one of its clusters; the message names the deployment and the clusterReference where resources remain. Before removing a deployment’s local entry, solo checks each attached cluster and refuses to proceed if it still hosts components (mirror node, relay, explorer, block node, or the consensus network), since deleting the entry would orphan those running workloads. Destroy the components first, then delete the deployment.

Troubleshooting Steps

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

5 - SOLO-2005

DeploymentDeleteFailedError

Description

Thrown when removing a deployment fails; the underlying failure is wrapped in cause. Deleting a deployment removes its entry from the local configuration and may reach into each attached cluster to clean up, so this is raised when that work cannot complete — most often because one of the deployment’s cluster references or its kubeconfig context is invalid or unreachable. It is retryable, since a transient connectivity problem often clears on a later attempt once the contexts are reachable again.

Troubleshooting Steps

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

6 - SOLO-2006

ClusterAddFailedError

Description

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

Troubleshooting Steps

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

7 - SOLO-2007

DeploymentListFailedError

Description

Thrown when solo deployment config list cannot enumerate the configured deployments; the underlying failure is wrapped in cause. Listing reads the deployment entries from the local configuration and may consult the clusters they reference, so this is raised when that read fails — for example the local config could not be read or parsed, or a referenced cluster could not be queried. It is retryable because transient filesystem or cluster issues often resolve on a later attempt.

Troubleshooting Steps

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

8 - SOLO-2008

ClusterReferenceNotFoundError

Description

Thrown when a command refers to a cluster reference that is not registered in the local configuration; the message names the missing reference. A cluster reference is the named link between solo and a kubeconfig context, created with solo cluster-ref config connect, so this is raised when the supplied name was never connected, was misspelled, or was disconnected. Connect the cluster reference (or correct the name) before retrying.

Troubleshooting Steps

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

9 - SOLO-2009

ClusterReferenceAlreadyExistsError

Description

Thrown when a cluster reference that is already attached to the deployment is added again; the message names the duplicate reference. solo keeps each cluster reference attached to a deployment at most once, so it rejects a second add rather than creating a conflicting duplicate entry. If you intend to re-add it (for example to change its binding), disconnect it first and then connect it again.

Troubleshooting Steps

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

10 - SOLO-2010

NamespaceNotSetError

Description

Thrown when a command needs a target Kubernetes namespace but none could be resolved. solo determines the namespace from the --namespace flag or from the selected deployment’s configuration, so this is raised when neither is available — the flag was not passed and the deployment has no namespace recorded. Supply --namespace, or select a deployment whose configuration defines one.

Troubleshooting Steps

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

11 - SOLO-2011

NoClustersForDeploymentError

Description

Thrown when an operation targets a deployment that has no clusters attached; the message names the deployment. A deployment must have at least one cluster reference attached before solo can place or manage its components, so this is raised when the deployment exists but its cluster list is empty — typically because solo deployment cluster attach has not yet been run for it. Attach a cluster to the deployment before retrying.

Troubleshooting Steps

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

12 - SOLO-2012

ClusterReferenceResolutionFailedError

Description

Thrown when solo cannot resolve which cluster reference a deployment should use; the message names the deployment. Internally a command expected the deployment to yield a single, unambiguous cluster reference (so it knows where to act) but the resolution returned nothing usable. While an unattached deployment is the visible trigger, this is classified as a Solo-owned error because the calling code should have ensured a cluster was attached before reaching this point — it points to a missing precondition in solo’s flow.

Troubleshooting Steps

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

13 - SOLO-2013

ContextNotFoundForClusterError

Description

Thrown when a cluster reference exists in the local configuration but has no kubeconfig context bound to it; the message names the cluster reference. solo needs the context to know which cluster the reference points at, so this is raised when the mapping is missing — usually because the reference was recorded without being connected to a context, or the binding was removed. Connect a kubeconfig context to the cluster reference before retrying.

Troubleshooting Steps

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

14 - SOLO-2014

NoDeploymentsFoundError

Description

Thrown when a command needs at least one deployment to act on but the local configuration contains none. solo stores every deployment in local config and several commands assume one already exists, so this is raised when that list is empty — typically because no deployment has been created yet, or because they were all deleted (or the active SOLO_HOME/local config does not contain any). Create a deployment before running the command.

Troubleshooting Steps

1. Create a deployment: solo deployment config create

15 - SOLO-2015

DeploymentListPortsFailedError

Description

Thrown when solo cannot enumerate the forwarded ports for a deployment; the underlying failure is wrapped in cause. Listing ports queries the Kubernetes API in the deployment’s namespace to discover the active port-forwards exposing its components, so this is raised when that query fails — typically because the cluster’s API server is unreachable or the namespace cannot be inspected. It is retryable, as a transient connectivity problem often clears on a later attempt.

Troubleshooting Steps

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

16 - SOLO-2016

ClusterSetupFailedSoloError

Description

Thrown when solo cluster-ref config setup cannot install the cluster-level shared infrastructure that deployments depend on — the solo-cluster-setup chart and its components (Prometheus, MinIO, metrics-server, and the cluster role). It wraps the underlying failure (cause.message), which is most often a failed Helm release (bad chart version or values), an image that cannot be pulled, missing RBAC permissions on the target cluster, or a cluster that lacks the CPU/memory to schedule the new pods.

Troubleshooting Steps

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

17 - SOLO-2017

ClusterResetFailedSoloError

Description

Thrown when solo cluster-ref config reset cannot tear down the cluster-level resources that setup installed (the solo-cluster-setup chart and its components); the underlying failure is wrapped in cause. It means the uninstall did not complete cleanly — for example a Helm release could not be removed, or the cluster API was unreachable mid-reset — so some resources may still be present. Inspect the remaining Helm releases and pods to see what was left behind.

Troubleshooting Steps

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

18 - SOLO-2018

MinioInstallFailedSoloError

Description

Thrown during cluster setup when the MinIO Operator Helm chart fails to install; the underlying failure is wrapped in cause. MinIO provides the S3-compatible object storage that solo’s cluster-level stack relies on, so its install is part of solo cluster-ref config setup. The failure is usually a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster lacking the resources/connectivity to schedule the operator.

Troubleshooting Steps

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

19 - SOLO-2019

PrometheusInstallFailedSoloError

Description

Thrown during cluster setup when the Prometheus stack Helm chart fails to install; the underlying failure is wrapped in cause. The Prometheus stack supplies the monitoring and metrics collection for the cluster-level stack installed by solo cluster-ref config setup. The failure is typically a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster without the resources/connectivity to schedule its pods.

Troubleshooting Steps

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

20 - SOLO-2020

MetricsServerInstallFailedSoloError

Description

Thrown during cluster setup when the metrics-server Helm chart fails to install; the underlying failure is wrapped in cause. metrics-server provides the resource-usage metrics API the cluster-level stack depends on, installed as part of solo cluster-ref config setup. The failure is usually a Helm error (bad chart version or values), an image that cannot be pulled, or a cluster lacking the resources/connectivity to schedule the pod.

Troubleshooting Steps

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

21 - SOLO-2021

ClusterRoleInstallFailedSoloError

Description

Thrown during cluster setup when the pod-monitor-role ClusterRole cannot be installed; the underlying failure is wrapped in cause. This ClusterRole grants the monitoring stack permission to scrape pods cluster-wide, so it is created as part of solo cluster-ref config setup. The failure most often means the current kubeconfig user lacks the RBAC permission to create ClusterRoles, but it can also stem from an API server that is unreachable or rejected the request.

Troubleshooting Steps

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

22 - SOLO-2022

ClusterApiServerTimeoutSoloError

Description

Thrown when a cluster’s Kubernetes API server does not become ready within the allowed number of attempts; the message names the context and the maxAttempts tried, and wraps the last failure in cause. solo polls the API server before proceeding so it does not act against a cluster that is still starting, and raises this once polling is exhausted. It is retryable because a cluster that is merely slow to come up (for example a Kind cluster still initialising) often becomes ready shortly after; a persistent failure points to a cluster that is down, unreachable, or pointed at by the wrong context.

Troubleshooting Steps

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

23 - SOLO-2023

KindClusterNetworkSetupFailedSoloError

Description

Thrown when solo cannot configure networking for a Kind cluster — either the Kind network setup itself or the MetalLB Helm repository configuration it depends on; the underlying failure is wrapped in cause. solo configures MetalLB so that LoadBalancer services in the local Kind cluster receive reachable addresses, and raises this when that setup fails. Common roots are Docker not running (Kind needs it), an unreachable or misconfigured Helm repository, or a problem with the Kind cluster’s Docker network.

Troubleshooting Steps

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

24 - SOLO-2024

BackupExportFailedSoloError

Description

Thrown during solo config ops backup when a particular resource cannot be exported into the backup; the message names the resourceType and wraps the underlying failure in cause. Backup reads each resource from the cluster and writes it to the backup archive, so this is raised when reading a resource or writing it out fails — for example the Kubernetes API is unreachable, the deployment or resource no longer exists, or the archive destination cannot be written.

Troubleshooting Steps

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

25 - SOLO-2025

BackupImportFailedSoloError

Description

Thrown during solo config ops restore-config when a particular resource cannot be imported from a backup; the message names the resourceType and wraps the underlying failure in cause. Restore reads each resource from the backup archive and applies it to the cluster, so this is raised when reading the archive entry or applying it fails — for example the backup archive is incomplete or corrupt, the resource is invalid, or the Kubernetes API is unreachable or rejected it.

Troubleshooting Steps

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

26 - SOLO-2026

BackupRestoreClustersFailedSoloError

Description

Thrown when solo config ops restore-clusters cannot recreate the clusters captured in a backup; the underlying failure is wrapped in cause. This step reads the backup archive and rebuilds the cluster(s) it describes (for example recreating a Kind cluster) before the rest of a restore can proceed, so the error means that rebuild failed. Common roots are an invalid or incomplete backup archive, an incorrect input directory, or Docker/Kind not being available to create the clusters.

Troubleshooting Steps

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

27 - SOLO-2027

DeployNetworkFailedSoloError

Description

Thrown when solo consensus network deploy cannot bring up the consensus network; the underlying failure is wrapped in cause. This step installs the solo-deployment Helm chart that creates the consensus node pods and their supporting services, so the error means that install did not succeed. Typical roots are a Helm release failure (bad chart version or values), an image that cannot be pulled, insufficient cluster resources to schedule the nodes, or a loss of connectivity to the cluster during the deploy.

Troubleshooting Steps

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

28 - SOLO-2028

InitFailedSoloError

Description

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

Troubleshooting Steps

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

29 - SOLO-2029

BlockNodeClusterContextNotFoundSoloError

Description

Thrown when solo needs to act on a block node but cannot determine which cluster (kubeconfig context) it lives in; the message names the blockNodeId. solo maps each block node to a registered cluster reference to find the context for its operations, so this is raised when no such mapping resolves — typically because the block node is not associated with a registered cluster reference, or the referenced cluster is missing from the deployment configuration.

Troubleshooting Steps

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

30 - SOLO-2030

MirrorNodeClusterContextNotFoundSoloError

Description

Thrown when solo needs to act on a mirror node but cannot determine which cluster (kubeconfig context) it lives in; the message names the mirrorNodeId. solo maps each mirror node to a registered cluster reference to find the context for its operations, so this is raised when no such mapping resolves — typically because the mirror node is not associated with a registered cluster reference, or the referenced cluster is missing from the deployment configuration.

Troubleshooting Steps

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