Configuration

• 1: SOLO-1001
• 2: SOLO-1002
• 3: SOLO-1003
• 4: SOLO-1004
• 5: SOLO-1005
• 6: SOLO-1006
• 7: SOLO-1007
• 8: SOLO-1008
• 9: SOLO-1009

1 - SOLO-1001

LocalConfigNotFoundSoloError

Description

Thrown when solo reads its local configuration but no file exists at the resolved path (~/.solo/local-config.yaml, or $SOLO_HOME/local-config.yaml when SOLO_HOME is set). The local config records cluster references, deployments, and the active user context, so most commands load it before doing any work. solo creates the file the first time a command loads it, so a missing file means SOLO_HOME points at a different directory than the one the file was created in, or that it was manually moved or deleted.

Troubleshooting Steps

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

2 - SOLO-1002

WriteLocalConfigFileError

Description

Thrown when solo cannot persist the local configuration to disk at ~/.solo/local-config.yaml (or $SOLO_HOME/local-config.yaml). The local config is rewritten whenever solo records a new cluster reference, deployment, or context, and this error wraps the underlying filesystem failure (cause). It means the data was prepared but could not be written: typical causes are missing write permissions on the ~/.solo directory, a read-only or full disk, or a parent directory that is missing or locked.

Troubleshooting Steps

1. Check file system permissions for ~/.solo

3 - SOLO-1003

RefreshLocalConfigSourceError

Description

Thrown when solo fails to reload the local configuration from its on-disk source — that is, the re-read and re-parse of ~/.solo/local-config.yaml (or $SOLO_HOME/local-config.yaml) did not complete; the message names the offending file and the underlying failure is wrapped in cause. Unlike LocalConfigNotFoundSoloError, the file is present: it could not be read (insufficient permissions, an I/O error) or its contents could not be parsed into the expected configuration because the file is malformed or corrupt. A malformed file can be regenerated from a cluster’s remote config with solo deployment config import.

Troubleshooting Steps

1. Check file system permissions and contents of the file:

4 - SOLO-1004

RemoteConfigsMismatchSoloError

Description

Thrown when a deployment spans multiple clusters and solo finds that the remote configuration stored in two of them does not agree; the message names the two clusters whose copies diverged. solo keeps the remote config as a ConfigMap that must be an identical replica in every cluster of the deployment, so it compares them and raises this when they differ. The usual cause is a prior write that was applied to one cluster but not the others (a partial or failed update), a ConfigMap that was edited manually, or clusters that have otherwise drifted out of sync.

Troubleshooting Steps

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

5 - SOLO-1005

IncompleteLocalConfigError

Description

Thrown when the local configuration file (~/.solo/local-config.yaml, or $SOLO_HOME/local-config.yaml) parses as valid YAML but is missing required top-level keys such as deployments or clusterRefs; the message names the file and the missing keys. Without this check a partial file — typically left behind by an interrupted write or a manual edit — would silently load as a valid-but-empty config and only surface later as a confusing DeploymentNotFoundError. The file can be regenerated from a cluster’s remote config with solo deployment config import.

Troubleshooting Steps

1. Or restore the missing keys in the file manually:

6 - SOLO-1006

RemoteConfigDataInvalidSoloError

Description

Thrown when the remote configuration stored in the solo-remote-config ConfigMap cannot be turned into a configuration object: the remote-config-data value is empty, is not parseable as YAML, or parses to something that is not a configuration object (a bare scalar, null, or a sequence). solo treats that ConfigMap as the source of truth for a deployment and reads it before almost any other work, so an unusable value blocks the whole command. The value is normally only written by solo itself, so this means it was hand-edited, truncated by a partial or interrupted write, or otherwise corrupted in the cluster. The offending value is captured on the error (meta.capturedData) so it can be inspected after the fact.

Troubleshooting Steps

1. Inspect the stored value: kubectl get configmap solo-remote-config -n -o yaml
2. The full captured value is recorded in ~/.solo/logs/solo.log
3. Recover by deleting and recreating the cluster: solo one-shot single destroy, then solo one-shot single deploy
4. Collect a diagnostics bundle: solo deployment diagnostics debug
5. If this is reproducible or looks like a solo bug, open an issue or PR with the diagnostics bundle: https://github.com/hiero-ledger/solo/issues

7 - SOLO-1007

MigrateLegacyLocalConfigError

Description

Thrown when solo cannot migrate the legacy local configuration from the old cache path ($SOLO_HOME/cache/local-config.yaml) to the current path ($SOLO_HOME/local-config.yaml). The migration copies the legacy file to the current path and validates it before the legacy file is removed, so this error is raised either because a filesystem operation failed (copy/remove/mkdir, wrapped in cause) or because the legacy configuration is corrupt and cannot be parsed. In both cases the legacy file is left in place — it is never deleted while unvalidated — and the corrupt copy (if any) is discarded, so no configuration is silently propagated or lost.

Troubleshooting Steps

1. Inspect the legacy file at . If it is corrupt, fix the YAML or remove it, then re-run the command. Also verify file system permissions for your Solo home directory.Inspect the legacy local configuration file. If it is corrupt, fix the YAML or remove it, then re-run the command. Also verify file system permissions for your Solo home directory.

8 - SOLO-1008

RemoteConfigMissingOnKindClusterError

Description

Thrown when the solo-remote-config ConfigMap that backs a deployment cannot be found and the deployment targets a local kind cluster. solo keeps the authoritative deployment state in that ConfigMap, so its absence means the deployment recorded in the local config no longer has anything backing it in the cluster; the usual causes are a kind cluster that was deleted and recreated, a namespace that was removed with kubectl, or a ConfigMap that was deleted by hand. A local kind cluster holds nothing worth preserving, so the recorded deployment cannot be resumed and the fix is to tear the leftover state down with solo one-shot single destroy and deploy again from a clean slate. solo one-shot single deploy detects this state up front and offers that teardown itself; every other command reports this error and stops. Deployments on non-kind clusters fail with the generic resource-not-found error instead, since their state may still be recoverable.

Troubleshooting Steps

1. Confirm the kind cluster and namespace still exist: kind get clusters && kubectl get namespaces
2. Inspect the remote config ConfigMap: kubectl get configmap solo-remote-config -n
3. Tear the leftover state down before deploying again: solo one-shot single destroy –deployment

9 - SOLO-1009

RemoteConfigMissingForDeployError

Description

Thrown by network deploy when the solo-remote-config ConfigMap that backs a deployment cannot be found. network destroy leaves the namespace and the recorded deployment in place unless it is asked to remove PVCs and secrets as well, so the deployment itself is not gone — only the ConfigMap tracking it. deployment cluster attach only (re)creates that ConfigMap when the deployment has no clusters recorded yet; once a cluster-ref is already attached it instead expects the ConfigMap to exist and fails the same way. The only way back to a working state is therefore to delete and recreate the deployment’s local config so the cluster-ref attach is treated as new, which recreates the ConfigMap fresh. The consensus keys have to be regenerated alongside it, since a successful network deploy removes the cached copies from disk once they are uploaded to cluster secrets.

Troubleshooting Steps

1. Inspect the remote config ConfigMap: kubectl get configmap solo-remote-config -n
2. The deployment record still exists locally, but the remote config backing it is gone and cannot be recreated in place. Recreate the local deployment config so cluster attach treats it as new, then reattach the cluster and regenerate the consensus keys:
3. solo deployment config delete –deployment
4. solo deployment config create -d -n -q
5. solo deployment cluster attach -d -c -q –num-consensus-nodes
6. solo keys consensus generate -d -q –gossip-keys –tls-keys
7. Set –num-consensus-nodes to the node count this deployment had before, then re-run network deploy