Error Codes

Purpose: For operators, provides a lookup table of error codes grouped by category with messages and resolution steps.

Error Code Format

Error codes follow the pattern E<category><number>:

Prefix	Category	Range
E1xx	CLI errors	E100–E199
E2xx	Validation errors	E200–E299
E3xx	Provisioning errors	E300–E399
E4xx	GitOps errors	E400–E499

CLI Errors (E1xx)

Code	Message	Resolution
E100	no cluster name provided and no active cluster set	Run opencenter cluster use <name> or pass the cluster name as argument.
E101	cluster not found: <name>	Verify cluster exists: opencenter cluster list. Check organization name if using org/cluster format.
E102	configuration file not found	Run opencenter cluster init <name> to create the configuration.
E103	failed to resolve path for cluster	Ensure configuration directory exists: ~/.config/opencenter/clusters.
E104	unsupported infrastructure provider: <name>	Use one of: openstack, aws, gcp, azure, baremetal, vsphere, vmware, kind.
E105	command not found: <tool>	Install the required tool. Check PATH includes the tool binary.
E106	permission denied: <path>	Check file/directory permissions. Cluster secrets require 0600.
E107	cluster name cannot be empty	Provide a cluster name. Names must be lowercase alphanumeric with hyphens.
E108	invalid cluster name format	Use lowercase letters, numbers, and hyphens. Must start and end with alphanumeric. Max 63 characters.
E109	organization name format invalid	Use lowercase letters, numbers, and hyphens. No path separators.
E110	configuration already exists (use --force to overwrite)	Pass --force to overwrite or choose a different cluster name.
E111	active cluster session conflict	Another session is using this cluster. Wait or use --force.
E112	CLI version incompatible with cluster schema	Upgrade the CLI: opencenter self-update or use the version matching your cluster.

Validation Errors (E2xx)

Code	Message	Resolution
E200	schema validation failed	Run opencenter cluster validate --verbose for detailed field errors.
E201	required field missing: <path>	Add the missing field to your configuration file.
E202	invalid type for <field>: expected <type>	Correct the field value type (e.g., integer instead of string).
E203	invalid CIDR format: <field>	Use valid CIDR notation (e.g., 10.42.0.0/16). Prefix length must be 0–32.
E204	subnet overlap detected	Use non-overlapping CIDR ranges for pod, service, and node subnets.
E205	vrrp_ip must be set when use_octavia=false and vrrp_enabled=true	Set networking.vrrp_ip or enable Octavia.
E206	exactly one network_plugin must be enabled	Enable only one of: calico, cilium, kube-ovn.
E207	unsupported deployment method: <name>	Use kubespray or kamaji.
E208	cross-field dependency violation	Check that conditional fields match. Run opencenter cluster validate --verbose.
E209	OpenStack auth URL is not a valid absolute URL	Set a full URL: https://identity.example.com:5000/v3.
E210	SOPS key validation failed	Generate a key: opencenter secrets keys generate. Verify the key file exists and has correct format.
E211	gitops repository URL must use ssh or https	Use ssh://git@... or https://... format. HTTP is not accepted.
E212	service <name> requires secret: <path>	Set the required secret value in your configuration.
E213	OpenStack network_plugin cannot use install_method "kubespray"	Use helm or kustomize-helm for OpenStack CNI install method.
E214	configuration is nil	Internal error. Re-run opencenter cluster init.
E215	invalid enum value for <field>	Check allowed values in the configuration schema.

Provisioning Errors (E3xx)

Code	Message	Resolution
E300	infrastructure provisioning failed	Check OpenTofu logs in the state directory. Verify cloud credentials.
E301	failed to reach OpenStack auth URL	Verify network access to the Keystone endpoint. Check firewall rules.
E302	OpenStack authentication failed	Verify application credentials. Check project/domain names.
E303	image ID not found in OpenStack	Verify the image exists: openstack image show <id>.
E304	flavor not found	List available flavors: openstack flavor list. Update config.
E305	quota exceeded	Request quota increase or reduce resource requests.
E306	network not found	Verify network exists and is accessible from the project.
E307	timeout waiting for cluster to be ready	Check node health. Inspect kubelet logs on control plane nodes.
E308	SSH connection failed to node	Verify bastion connectivity, SSH key, and security group rules.
E309	Kubespray playbook failed	Review Ansible output. Common: package install timeout, network issues.
E310	kind cluster creation failed	Check Docker is running. Verify port conflicts on 6443.
E311	terraform state locked	Another operation is running. Wait or manually unlock: tofu force-unlock <id>.
E312	kubeconfig not found after deploy	Check bootstrap logs. The kubeconfig is written to the state directory.

GitOps Errors (E4xx)

Code	Message	Resolution
E400	GitRepository auth failed	Recreate the SSH deploy key: flux create secret git.
E401	Kustomization path not found	Verify the --path matches the directory structure in the repository.
E402	SOPS decryption failed	Recreate the Age secret: kubectl create secret generic sops-age --from-file=age.agekey=<keyfile> -n flux-system.
E403	HelmRelease stuck in Installing	Image pull failure. Verify registry access and containerd mirror configuration.
E404	manifest validation failed	Run kustomize build locally. Check YAML syntax.
E405	git push failed: authentication	Verify token or deploy key has write access to the repository.
E406	gitops.git_dir must be configured	Set opencenter.gitops.repository.local_dir in cluster config.
E407	unencrypted secrets detected	Run opencenter secrets sync to encrypt. Do not commit plaintext secrets.
E408	stub secrets must be replaced	Replace CHANGEME/PLACEHOLDER values with actual credentials.
E409	flux bootstrap failed	Check token validity. Verify the repository exists and token has admin access.
E410	reconciliation timeout	Check flux events. Common: dependency not ready, resource conflict.
E411	gitops-base tag not found	Verify the tag exists in the openCenter-gitops-base repository. Update to a valid release.
E412	dirty working tree prevents deploy	Commit or stash changes: git add . && git commit or git stash.
E413	origin remote URL mismatch	The local remote doesn't match gitops.repository.url. Run git remote set-url origin <url>.

Structured Error Output

For CI/CD pipelines, use JSON output:

opencenter cluster validate --output json

Returns:

{
  "valid": false,
  "target": {"cluster": "prod-cluster", "organization": "myorg", "provider": "openstack"},
  "mode": "offline",
  "summary": {"total_errors": 2, "total_warnings": 1},
  "errors": [
    {
      "section": "Infrastructure > Cloud",
      "field": "auth_url",
      "yaml_path": "opencenter.infrastructure.cloud.openstack.auth_url",
      "message": "OpenStack auth URL is required",
      "severity": "error",
      "suggestion": "Set opencenter.infrastructure.cloud.openstack.auth_url"
    }
  ]
}