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" (AWS/GCP)​

Cause: Cloud dependencies not installed

Solution:

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

Issue: "AWS authentication failed" / permission check fails​

Cause: AWS CLI not authenticated, or the current identity can't bootstrap a deployment

Solution:

aws sts get-caller-identity   # confirms who you're authenticated as
aws configure                 # re-authenticate if needed

If authentication succeeds but the install still reports insufficient permissions, see Required AWS Permissions — an account with AdministratorAccess always satisfies this.

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

AWS Deployment Issues​

Issue: Terraform errors during provisioning​

Symptoms: Deployment fails during infrastructure creation

Diagnosis:

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

# View detailed error
terraform plan

Common Solutions:

  1. Stale credentials:

    env | grep -i AWS_
    unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
    aws sts get-caller-identity

    Leftover environment variables from an unrelated session silently override ~/.aws/credentials.

  2. Permission denied:

    aws sts get-caller-identity
    aws iam simulate-principal-policy \
      --policy-source-arn <your ARN> \
      --action-names iam:CreateUser iam:AttachUserPolicy iam:CreateAccessKey

  3. Resource already exists:

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

Issue: Deploy stuck waiting for DNS delegation​

Symptoms: The installer pauses after printing nameservers and doesn't proceed

Cause: Unlike GCP, AWS's certificate validation is synchronous — the installer deliberately waits here rather than finishing and catching up later

Solution:

  1. Confirm the NS records were added at your registrar exactly as printed — see How to delegate a subdomain

  2. Check propagation directly:

    dig NS ekai.yourcompany.com

  3. If it's taking longer than expected, it's safe to re-run the same install command later — the Route53 zone already exists, so that step is a fast no-op and it picks up waiting for delegation again

Issue: SSL certificate not provisioning​

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

Diagnosis:

aws acm list-certificates --region <your-region>
aws acm describe-certificate --certificate-arn <arn> --region <your-region>

Solution:

Since AWS validates the certificate synchronously during the deploy, this almost always traces back to DNS delegation — see the issue above.

Issue: DNS not resolving​

Symptoms: Domain doesn't reach the application

Diagnosis:

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

Solution:

  1. Confirm you completed NS delegation using the nameservers from the installer's output.

  2. Wait for propagation (minutes to a few hours; can take longer in some cases). Monitor with dnschecker.org.

  3. Flush local DNS cache if needed:

    # 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 the node group if needed
    aws eks update-nodegroup-config \
      --cluster-name ekai-production-eks \
      --nodegroup-name <nodegroup-name> \
      --scaling-config minSize=2,maxSize=6,desiredSize=4 \
      --region <your-region>

  2. Image pull errors:

    • Check image repository access
    • Verify service account permissions

  3. Configuration errors:

    • Check ConfigMaps and Secrets
    • Verify environment variables

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. Confirm you completed NS delegation using the nameservers from the installer’s success output.

  2. Wait for propagation (minutes to a few hours; can take longer in some cases). Monitor with dnschecker.org.

  3. Flush local DNS cache if needed:

    # 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

AWS:

# Check security groups attached to the Application Load Balancer
aws elbv2 describe-load-balancers --region <your-region>
aws ec2 describe-security-groups --group-ids <sg-id> --region <your-region>

# The ALB should auto-configure ingress rules via the Load Balancer Controller
# If issues persist, check the Target Groups' health in the EC2 Console

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​