Skip to main content

Troubleshooting Guide

Common issues and solutions when working with Orchestr8.

Platform Health​

Doctor Command​

The o8 doctor command is your first line of defense for diagnosing issues:

# Basic health check
o8 doctor

# Verbose diagnostics
o8 doctor --verbose

# Show fix suggestions
o8 doctor --fix

Platform Status​

# Check platform components
o8 status

# List all applications
o8 apps

# Check specific application
o8 apps status my-app

Common Issues​

1. CLI Installation Problems​

Issue: o8 command not found

# Verify installation
uv tool list | grep orchestr8

# Reinstall if needed
uv tool install orchestr8-platform --force

Issue: Permission errors

# On Linux/macOS, ensure PATH includes uv tools
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. Kubernetes Connection Issues​

Issue: kubectl context not set

# List available contexts
kubectl config get-contexts

# Set correct context
kubectl config use-context your-cluster-context

# Verify connection
kubectl cluster-info

Issue: Cluster not accessible

# For local development
docker desktop start  # or start minikube/kind

# For cloud providers
gcloud auth login      # GCP
aws configure         # AWS  
az login             # Azure

3. ArgoCD Issues​

Issue: Applications stuck in "Progressing" state

# Check ArgoCD logs
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller

# Force refresh application
kubectl patch app my-app -n argocd --type=merge -p='{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"now"}}}'

# Manual sync
o8 sync my-app --force

Issue: ArgoCD UI not accessible

# Check ArgoCD server status
kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server

# Port forward for local access (if needed)
kubectl port-forward svc/argocd-server -n argocd 8080:80

4. Module Deployment Issues​

Issue: Module fails to deploy

# Check module validation
o8 module validate ./my-module

# Check deployment logs
kubectl logs -n my-module deployment/my-module

# Check events
kubectl get events -n my-module --sort-by='.lastTimestamp'

Issue: Image pull errors

# Check if image exists
docker pull your-image:tag

# Verify image registry authentication
kubectl get secret -n my-module | grep regcred

# Check node logs for pull errors
kubectl describe pod pod-name -n my-namespace

5. Networking Issues​

Issue: Service mesh connectivity problems

# Check Istio sidecar injection
kubectl get pods -n my-namespace -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].name}{"\n"}{end}'

# Verify service mesh configuration
istioctl analyze -n my-namespace

# Check network policies
kubectl get networkpolicy -n my-namespace

Issue: Ingress not working

# Check ingress controller
kubectl get pods -n istio-system -l app=istio-ingressgateway

# Verify ingress configuration
kubectl get gateway,virtualservice -n my-namespace

# Check external IP
kubectl get svc -n istio-system istio-ingressgateway

6. Secrets Management Issues​

Issue: External Secrets not syncing

# Check External Secrets Operator
kubectl get pods -n external-secrets-system

# Check SecretStore configuration
kubectl get secretstore,externalsecret -n my-namespace

# Check ESO logs
kubectl logs -n external-secrets-system -l app.kubernetes.io/name=external-secrets

Issue: Cloud provider authentication

# AWS - verify credentials
aws sts get-caller-identity

# GCP - verify auth
gcloud auth list

# Azure - verify login
az account show

7. Performance Issues​

Issue: Slow deployment times

  • Check cluster resources: kubectl top nodes
  • Review image sizes and optimization
  • Verify network connectivity to registries
  • Check for resource constraints

Issue: High memory/CPU usage

# Check resource usage
kubectl top pods -n my-namespace

# Review resource limits
kubectl describe deployment my-app -n my-namespace

# Check cluster capacity
kubectl describe nodes

Getting Help​

Log Collection​

# Collect platform logs
o8 doctor --verbose > orchestr8-diagnostics.log

# Collect Kubernetes logs
kubectl logs --previous -n argocd deployment/argocd-application-controller > argocd-logs.txt

# Export cluster info
kubectl cluster-info dump > cluster-info.txt

Support Channels​

Debug Mode​

Enable debug logging for more detailed troubleshooting:

# Enable debug mode
export O8_DEBUG=true

# Run commands with verbose output
o8 setup --provider local --verbose