Skip to main content

Troubleshooting

Common issues and solutions organized by deployment stage.

Installation Issues​

Issue: "Native Windows is not supported"​

Cause: Running the install on Windows outside WSL2

Solution:

  1. Install WSL2
  2. Install Ubuntu from the Microsoft Store
  3. Open an Ubuntu terminal and start the install again from licensing.ekai.ai
Windows Users

The install must be run inside WSL2. Native Windows PowerShell/CMD is not supported.

Issue: "Missing required tools" (GCP)​

Cause: GCP dependencies not installed

Solution:

Accept the auto-install prompt when offered, or install the tools yourself using the official documentation linked in Prerequisites.

Issue: "GCP authentication failed"​

Cause: gcloud CLI not authenticated or wrong project

Solution:

gcloud auth login

Issue: Installation interrupted or timed out​

Cause: Network disconnection, system sleep, or long-running operation timeout

Solution:

Return to licensing.ekai.ai and follow the install instructions again.

When prompted, choose to resume the previous deployment:

Found previous run artifacts for GCP env 'production'.
Retry that deploy instead of starting a new one? [y/N]: y
Smart Resume

The install automatically resumes from the last successful step. It is safe to retry multiple times.

Local Deployment Issues​

Issue: "Docker daemon not running"​

Cause: Docker is not started

Solution:

# macOS
# Start Docker Desktop from Applications

# Linux
sudo systemctl start docker
sudo systemctl enable docker

# Verify
docker ps

Issue: "Port 80 already in use"​

Cause: Another service (Apache, Nginx, etc.) is using port 80

Solution:

Option 1 - Stop conflicting service:

# Find process using port 80
sudo lsof -i :80
sudo netstat -tulpn | grep :80

# Stop the service (example for Apache)
sudo systemctl stop apache2

Option 2 - Use different port:

Edit docker-compose.yml:

services:
  ekai-frontend:
    ports:
      - "8080:80" # Changed from "80:80"

Then access ekai at http://localhost:8080

Issue: Containers keep restarting​

Cause: Application errors or resource constraints

Solution:

# Check logs for specific errors
docker-compose logs

# Check resource usage
docker stats

# Common fixes:
# 1. Increase Docker memory/CPU limits
# 2. Fix environment variable issues
# 3. Ensure database is healthy before backend starts

GCP Deployment Issues​

Issue: Terraform errors during provisioning​

Symptoms: Deployment fails during infrastructure creation

Diagnosis:

# Check Terraform state
cd .self-deploy/terraform-google-ekai/
terraform state list

# View detailed error
terraform plan

Common Solutions:

  1. Quota exceeded:

    • Check GCP Console → IAM & Admin → Quotas
    • Request quota increase if needed

  2. Permission denied:

    # Verify your account permissions
    gcloud projects get-iam-policy YOUR_PROJECT_ID \
      --flatten="bindings[].members" \
      --filter="bindings.members:user:YOUR_EMAIL"

  3. Resource already exists:

    • Safe to re-run installer (Terraform is idempotent)
    • Or manually import existing resources

Issue: SSL certificate not provisioning​

Symptoms: "Certificate not trusted" warnings or HTTP (not HTTPS)

Diagnosis:

kubectl describe certificate -n ekai
kubectl logs -n cert-manager deployment/cert-manager

Solution:

  1. Wait longer: Let's Encrypt provisioning takes 10-15 minutes

  2. Verify DNS records:

    dig ekai.yourcompany.com
    # Should return the LoadBalancer IP

  3. Check cert-manager logs:

    kubectl logs -n cert-manager deployment/cert-manager
    # Look for ACME challenge errors

  4. Manual troubleshooting:

    # Delete and recreate certificate
    kubectl delete certificate ekai-tls -n ekai
    # Wait for automatic recreation

Issue: DNS not resolving​

Symptoms: Domain doesn't reach the application

Diagnosis:

dig ekai.yourcompany.com
nslookup ekai.yourcompany.com

Solution:

  1. Verify DNS records exist:

    • Check your DNS provider's console
    • Ensure A records point to LoadBalancer IP

  2. Get LoadBalancer IP:

    kubectl get svc -n ekai ekai-ingress \
      -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

  3. Wait for propagation:

    • DNS propagation can take up to 48 hours
    • Typically completes in 5-10 minutes
    • Use dnschecker.org to monitor

  4. Flush local DNS cache:

    # macOS
    sudo dscacheutil -flushcache

    # Linux
    sudo systemd-resolve --flush-caches

    # Windows (in Admin CMD)
    ipconfig /flushdns

Issue: Pods not starting​

Symptoms: Pods stuck in "Pending" or "CrashLoopBackOff"

Diagnosis:

kubectl get pods -n ekai
kubectl describe pod <pod-name> -n ekai
kubectl logs <pod-name> -n ekai

Common Causes & Solutions:

  1. Insufficient cluster resources:

    # Check node resources
    kubectl top nodes

    # Scale cluster if needed
    gcloud container clusters resize ekai-production-gke \
      --num-nodes=5 \
      --region=us-central1

  2. Image pull errors:

    • Check image repository access
    • Verify service account permissions

  3. Configuration errors:

    • Check ConfigMaps and Secrets
    • Verify environment variables

Network & Firewall Issues​

Issue: Cannot access frontend from outside​

Cause: Firewall blocking required ports

Solution:

Local:

# Allow Docker ports (if firewall enabled)
sudo ufw allow 80/tcp
sudo ufw allow 3000/tcp

GCP:

# Check firewall rules
gcloud compute firewall-rules list

# LoadBalancer should auto-configure ingress
# If issues persist, check Load Balancer configuration in GCP Console

Issue: Slow performance or timeouts​

Symptoms: Pages load slowly, API timeouts

Diagnosis:

# Local
docker stats

# Cloud
kubectl top pods -n ekai
kubectl top nodes

Solutions:

  1. Increase allocated resources:

    Local - Edit docker-compose.yml:

    ekai-backend:
      deploy:
        resources:
          limits:
            memory: 4G
            cpus: "2"

  2. Scale up (Cloud):

    kubectl scale deployment ekai-backend --replicas=3 -n ekai

  3. Check database performance:

    • Review slow query logs
    • Check connection pool settings
    • Increase database resources if needed

Getting Help​

If your issue isn't covered here:

  1. Gather Information:

    • Deployment mode (local/cloud)
    • Operating system and version
    • Complete error messages
    • Relevant logs (last 100 lines minimum)
    • Steps to reproduce

  2. Check Logs:

    # Local
    docker-compose logs > logs.txt

    # Cloud
    kubectl logs deployment/ekai-backend -n ekai --tail=500 > backend-logs.txt
    kubectl logs deployment/ekai-frontend -n ekai --tail=500 > frontend-logs.txt

  3. Contact Support:

    • Email: support@ekai.ai
    • Include all gathered information and logs
    • Specify urgency and impact

Next Steps​