Minikube Troubleshooting: AI-Optimized Knowledge Base

Critical Context

• Failure Rate: High - Minikube breaks frequently, especially after system restarts, driver changes, or BIOS modifications
• Debugging Time Investment: 30 minutes to 4+ hours per incident, depending on root cause
• Operational Reality: "Nuclear option" (delete/restart) succeeds 50% of the time, saving hours of debugging

Startup Failures: Configuration and Solutions

minikube start Hangs (High Frequency Issue)

Problem: Command hangs indefinitely without error messages
Root Causes:

• Virtualization disabled in BIOS (most common)
• Driver incompatibility
• Resource conflicts

Solution Hierarchy:

1. Nuclear option (50% success rate, 2 minutes):

   minikube delete
   minikube start --driver=docker --memory=4096
   

2. Virtualization verification (10 minutes if successful, hours if BIOS locked):

   # Linux - should return >0
   egrep -c '(vmx|svm)' /proc/cpuinfo
   # macOS
   sysctl -a | grep machdep.cpu.features
   

3. Driver fallbacks:

   minikube start --driver=virtualbox  # Slow but reliable
   minikube start --driver=hyperv      # Windows only
   

Critical Warning: Corporate laptops often have virtualization locked in BIOS - use Docker driver as workaround

VT-X/AMD-v Disabled Error

Problem: Hardware virtualization not enabled
Time Investment: 10 minutes if accessible, permanent failure if corporate-locked
Solution: BIOS configuration (F2/F12/Delete key varies by manufacturer)

• Intel: "Intel VT-x", "Virtualization Technology", "VMX"
• AMD: "AMD-V", "SVM Mode"
  Workaround: --driver=docker (no hardware virtualization required)

Platform-Specific Failures

macOS: HyperKit/xhyve Crashes

Problem: HyperKit driver instability
Severity: High - crashes frequently, unreliable for development
Solution: Switch drivers

# Stable option (slower)
minikube start --driver=virtualbox
# Fast option  
minikube start --driver=docker

Windows: Hyper-V Issues

Problem: Hyper-V availability despite installation
Root Causes:

1. Docker Desktop conflict - stop before Minikube start
2. Missing Windows features
   Solution:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Networking Failures: Critical Production Blockers

LoadBalancer Services Stuck Pending

Problem: External IP shows <pending> indefinitely
Impact: Makes LoadBalancer services unusable, forces NodePort workarounds
Root Cause: Minikube lacks real load balancer (unlike AWS ELB/GCP LB)

Primary Solution: minikube tunnel

sudo minikube tunnel  # Requires sudo on Linux/macOS

Critical Warning: Tunnel crashes after laptop sleep, leaving services unreachable mid-demo

Production Workaround:

# Convert to NodePort (more reliable)
kubectl patch svc myservice -p '{"spec":{"type":"NodePort"}}'
minikube service myservice --url

DNS Resolution Failures

Problem: Pods cannot resolve service names
Frequency: Common after restarts or driver changes
Diagnosis:

kubectl run test-pod --image=busybox --rm -it -- nslookup kubernetes.default

Solution: CoreDNS restart

kubectl delete pods -n kube-system -l k8s-app=kube-dns

Docker Driver Networking Gotcha

Problem: Services unreachable despite successful deployment
Symptoms:

• kubectl port-forward works
• minikube service URLs fail
• NodePort services inaccessible from browser

Solution:

minikube ip  # If returns 127.0.0.1, you're in Docker mode
minikube service myservice --url  # Get actual accessible URL

Resource Management: Performance and Scaling

ImagePullBackOff Errors

Problem: Pods stuck in ImagePullBackOff state
Common Causes:

1. Private registry auth (most common):

   kubectl create secret docker-registry regcred \
     --docker-server=your-registry.com \
     --docker-username=your-user \
     --docker-password=your-pass
   

2. Local images unavailable:

   eval $(minikube docker-env)
   docker build -t myapp:latest .
   # OR
   minikube image load myapp:latest
   

OOMKilled Pods

Problem: Pods terminated for memory overconsumption
Diagnosis:

kubectl top pods
kubectl describe deployment myapp
kubectl get events --sort-by=.metadata.creationTimestamp

Solutions:

# Increase pod limit
kubectl patch deployment myapp -p '{"spec":{"template":{"spec":{"containers":[{"name":"myapp","resources":{"limits":{"memory":"512Mi"}}}]}}}}'
# OR increase cluster memory
minikube delete && minikube start --memory=8192

Disk Space Exhaustion

Problem: "No space left on device" during operations
Impact: Demo failures, deployment blocks
Root Causes:

• Docker image accumulation from testing
• Persistent log growth
• Forgotten PersistentVolumes

Solution Sequence:

minikube ssh
df -h  # Check usage
docker system prune -a -f  # Nuclear clean (loses cached layers)
sudo find / -type f -size +100M 2>/dev/null  # Find large files

Prevention:

minikube delete && minikube start --disk-size=50GB

Resource Requirements and Limitations

Memory Configuration

• Default: 2GB (insufficient for real development)
• Recommended Minimum: 4GB
• Production-like Testing: 8GB+

CPU and File Descriptor Limits

Problem: "Too many open files" errors
Solution:

ulimit -n 4096  # Temporary
echo "ulimit -n 4096" >> ~/.bashrc  # Permanent

Scheduling Failures

Problem: Pods stuck in "Pending" state
Diagnosis:

kubectl describe node minikube
kubectl describe pod <podname>

Common Fix:

kubectl patch deployment myapp -p '{"spec":{"template":{"spec":{"containers":[{"name":"myapp","resources":{"requests":{"memory":"128Mi","cpu":"100m"}}}]}}}}'

Emergency Procedures

Universal Debug Sequence

When networking completely fails:

minikube status
kubectl cluster-info dump | grep -i cidr
kubectl run test1 --image=busybox --rm -it -- ping 8.8.8.8
kubectl run test2 --image=busybox --rm -it -- nslookup kubernetes.default
minikube ssh 'sudo systemctl restart kubelet'  # Nuclear restart

Port Forward: Last Resort

When: All networking solutions fail
Reliability: High - bypasses Kubernetes networking

kubectl port-forward svc/myservice 8080:80

Quick Reference: Common Failures

Symptom	Root Cause	Time to Fix	Solution
minikube start hangs	Virtualization disabled	10min-4hrs	Enable VT-x/AMD-V in BIOS
LoadBalancer pending	No load balancer in Minikube	2min	minikube tunnel or switch to NodePort
ImagePullBackOff	Auth/image missing	5min	Create registry secret or load image
OOMKilled	Memory limit exceeded	2min	Increase pod limits or cluster memory
DNS resolution fails	CoreDNS broken	1min	Delete CoreDNS pods
"No space left"	Disk full	5min	docker system prune -a
Tunnel crashes	Network state corruption	2min	Kill tunnel, restart

Alternative Solutions

When Minikube Fails Completely

• Kind: Faster startup, better for CI/CD
• K3s: Lightweight, ARM-compatible
• Docker Desktop Kubernetes: If already using Docker Desktop

Resource Optimization

• Default Settings Fail: 2GB memory insufficient for multi-service development
• Recommended Production Testing: 8GB+ memory, 50GB+ disk
• Corporate Environment: Use Docker driver due to BIOS restrictions

Critical Warnings

1. minikube tunnel crashes after laptop sleep - always check tunnel status during demos
2. Corporate BIOS locks prevent virtualization changes - Docker driver mandatory
3. Default resource limits cause OOMKilled in real applications
4. CoreDNS breaks frequently after restarts - first thing to check for networking issues
5. Image cleanup required - default disk size fills quickly during development