CLI Errors & Exit Codes
Purpose: For operators, provides common CLI errors, exit code meanings, and resolution steps.
Exit Codes
| Code | Meaning | Action |
|---|---|---|
| 0 | Success | — |
| 1 | General error | Check stderr for details |
| 2 | Validation failure | Run opencenter cluster validate |
| 3 | Configuration not found | Verify cluster name and org |
Common Errors
no cluster name provided and no active cluster set
No argument was passed and no cluster is selected.
# Fix: select a cluster or pass the name explicitly
opencenter cluster select my-cluster
opencenter cluster validate
failed to load cluster configuration
The config file does not exist at the expected path.
Check the expected location:
~/.config/opencenter/clusters/<org>/<cluster>/.<cluster>-config.yaml
If the file exists but uses a different org, pass the full identifier:
opencenter cluster validate myorg/my-cluster
schema_version "1.0" is not supported
v1 configurations are not supported in CLI v2.0.0+. Upgrade to CLI v1.x first, run the migration, then upgrade to v2.
validation failed
The configuration has schema or business rule violations. Run with --verbose for details:
opencenter cluster validate my-cluster --verbose
failed to resolve ValidateService
Internal dependency injection failure. Usually caused by a corrupted install. Reinstall the CLI binary.
SOPS Age key not found
The Age key file referenced in the config does not exist. Regenerate keys:
opencenter cluster init my-cluster --regenerate-keys
Or generate keys for an existing cluster:
opencenter cluster init my-cluster --force
SSH key expired
SSH keys have a 180-day lifecycle. Rotate them:
opencenter cluster rotate-keys my-cluster
permission denied on config directory
The CLI cannot read or write to ~/.config/opencenter/. Check directory ownership:
ls -la ~/.config/opencenter/
Fix with:
chmod -R u+rw ~/.config/opencenter/
Debug Logging
Set --log-level debug for verbose output on any command:
opencenter cluster setup my-cluster --log-level debug
Or set the environment variable:
export OPENCENTER_LOG_LEVEL=debug
Reporting Issues
When filing a bug, include:
- CLI version:
opencenter version - Full command with
--log-level debug - Redacted config:
opencenter cluster validate my-cluster --generate-debug-config