Troubleshooting guide for common issues when deploying Koha on AWS using CloudFormation templates. This guide applies to all tiers: Free, Basic, Standard, and Enterprise.

CloudFormation Stack Issues

Stack Creation Failed

Symptoms:

  • Stack status shows CREATE_FAILED or ROLLBACK_COMPLETE
  • Resources are being deleted automatically

Solutions:

  1. Check Events Tab
    • Go to CloudFormation console
    • Select your stack
    • Click Events tab
    • Look for red error messages
    • Note the specific resource that failed

  2. Common Causes:

    Insufficient IAM Permissions:

    Error: User is not authorized to perform: iam:CreateRole
    • Solution: Ensure your IAM user/role has AdministratorAccess or CloudFormation-specific permissions
    • Contact your AWS administrator

    AWS Service Quotas Exceeded:

    Error: You have reached your limit of VPCs
    • Solution: Go to Service Quotas console
    • Request limit increase
    • Or delete unused resources

    Invalid Parameter Values:

    Error: Invalid instance type for architecture
    • Solution: Verify instance type matches AMI architecture
    • ARM64 AMIs require Graviton instances (m8g, m7g, etc.)
    • x86 AMIs require x86 instances (t3, m5, etc.)

    Availability Zone Issues (Enterprise):

    Error: Subnets must be in different Availability Zones
    • Solution: Select subnets in different AZs
    • Check subnet AZ in VPC console
  3. Delete Failed Stack: 
    aws cloudformation delete-stack --stack-name koha-library-stack
  4. Retry Deployment:
    • Fix the identified issue
    • Launch new stack with corrected parameters

Instance Access Issues

Can’t Access Koha URLs

Symptoms:

  • URLs timeout or refuse connection
  • Browser shows “This site can’t be reached”

Solutions:

  1. Wait for Services to Start:
    • Allow 2-5 minutes after CREATE_COMPLETE
    • Services need time to initialize
  2. Check Instance Status:
    • Go to EC2 Console → Instances
    • Verify instance is running
    • Ensure both status checks are passed (green checkmarks)
  3. Verify Security Groups:
    • Select instance → Security tab
    • Check inbound rules allow:
      • Port 8080 (OPAC) from 0.0.0.0/0
      • Port 8443 (Staff) from 0.0.0.0/0
    • For Enterprise: Check ALB security group allows 80/443
  4. Check Service Status via Instance Connect: 
    # Connect via EC2 Instance Connect
   
# Check Apache
sudo systemctl status apache2
   
# Check Koha services
sudo koha-plack --status library
sudo koha-worker --status library
   
# Restart if needed
sudo systemctl restart apache2
sudo koha-plack --restart library
  5. Review Instance Logs: 
    # Cloud-init logs
sudo tail -f /var/log/cloud-init-output.log
   
# Koha logs
sudo tail -f /var/log/koha/library/opac-error.log
sudo tail -f /var/log/koha/library/intranet-error.log

Password and Login Issues

Password Not Working

Symptoms:

  • “Invalid username or password” error
  • Can’t log in to staff interface

Solutions:

  1. Verify Password Retrieval:
    • Check you’re reading from correct Parameter Store path
    • Ensure no extra spaces when copying
    • Password is case-sensitive
  2. Get Password via Instance Connect: 
    # Connect to instance
# Then run:
sudo koha-passwd library
  3. Verify Correct URL:
    • Staff interface: Port :8443 or staff.yourdomain.com
    • OPAC (wrong): Port :8080 or library.yourdomain.com
    • Default username: koha_library
  4. Reset Password: 
    # Connect via Instance Connect
sudo koha-passwd library <new-password>

EC2 Instance Connect Issues

Can’t Connect via Instance Connect

Symptoms:

  • “Failed to connect” error in AWS Console
  • Timeout when using CLI

Solutions:

  1. Basic/Standard Tiers - Verify Endpoint Created:
    • Go to VPC Console → Endpoints
    • Look for Instance Connect Endpoint
    • Status must be Available
    • If missing: Create manually
  2. Enterprise Tier - Check Endpoint:
    • Endpoint is created automatically
    • Go to CloudFormation → Outputs
    • Find InstanceConnectEndpointId
    • Verify in VPC Console → Endpoints
  3. Verify Security Groups:
    • Templates configure security groups automatically
    • If customized, ensure Instance Connect prefix lists are allowed
    • Check both instance and endpoint security groups
  4. Check IAM Permissions: 
    {
  "Action": [
    "ec2-instance-connect:SendSSHPublicKey",
    "ec2:DescribeInstances"
  ]
}
  5. Try SSH Keys Instead:
    • Update stack with KeyPairName parameter
    • Use traditional SSH access

Backup Issues (Standard/Enterprise)

Backups Not Appearing in S3

Symptoms:

  • No files in S3 backup bucket
  • Backup logs show errors

Solutions:

  1. Check IAM Role Permissions: 
    # Verify IAM role attached to instance
aws ec2 describe-instances \
  --instance-ids i-xxxxx \
  --query 'Reservations[0].Instances[0].IamInstanceProfile'
  2. Verify Backup Cron Job: 
    # Check scheduled backups
sudo crontab -l | grep backup
  3. Check Backup Logs: 
    sudo tail -f /var/log/koha-backup.log
  4. Manual Test Backup: 
    sudo /usr/local/bin/koha-backup-to-s3.sh
  5. Verify S3 Bucket:
    • Check bucket exists in S3 console
    • Verify region matches deployment
    • Check lifecycle policies

SSL/Domain Issues (Standard)

SSL Certificate Request Failed

Symptoms:

  • Let’s Encrypt certificate request fails
  • Stack rolls back if SSL enabled during creation

Solutions:

  1. Verify DNS Resolution: 
    # From your computer
nslookup library.yourdomain.com
nslookup staff.yourdomain.com
    • Both should resolve to Elastic IP
    • Allow 5-60 minutes for DNS propagation
  2. Check Port 80 Accessibility: 
    # Test HTTP challenge endpoint
curl http://library.yourdomain.com/.well-known/acme-challenge/test
  3. Review Let’s Encrypt Logs: 
    sudo tail -f /var/log/letsencrypt/letsencrypt.log
  4. Manual Certificate Request: 
    # After DNS is configured
sudo koha-setup-domains --enable-ssl
  5. Common DNS Issues:
    • CNAME records (wrong) → Use A records
    • Pointing to instance ID instead of Elastic IP
    • TTL too high (use 300-600 seconds)

Database Issues (Enterprise)

Can’t Connect to Aurora Database

Symptoms:

  • “Can’t connect to MySQL server” errors
  • Koha shows database connection errors

Solutions:

  1. Check Security Groups:
    • Go to RDS Console → Databases
    • Click Aurora cluster
    • Check Connectivity & security tab
    • Verify security group allows port 3306 from EC2 instances
  2. Verify Credentials: 
    # Check Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id /koha/your-stack/db-credentials \
  --query SecretString --output text
  3. Test Connection from Instance: 
    # Get endpoint from CloudFormation Outputs
mysql -h <aurora-cluster-endpoint>.rds.amazonaws.com \
  -u kohaadmin -p koha_library
  4. Check Aurora Cluster Status:
    • Go to RDS Console
    • Verify cluster is Available
    • Check both writer and reader instances
  5. Review Aurora Logs:
    • RDS Console → Databases → Your cluster
    • Click Logs & events tab
    • Check error logs

Load Balancer Issues (Enterprise)

Getting 502/503 Errors

Symptoms:

  • “502 Bad Gateway” or “503 Service Unavailable”
  • Intermittent connection failures

Solutions:

  1. Check Target Health:
    • Go to EC2 Console → Load Balancers
    • Select your ALB
    • Click Target Groups tab
    • Verify targets are healthy
  2. Review Health Check Settings:
    • Health check path: /cgi-bin/koha/opac-main.pl
    • Healthy threshold: 2
    • Interval: 30 seconds
    • Timeout: 5 seconds
  3. Check Instance Services: 
    # On any instance
sudo systemctl status apache2
sudo koha-plack --status library
  4. Review ALB Logs:
    • Enable access logs in ALB settings
    • Check S3 bucket for logs
    • Look for 5xx status codes
  5. Verify Security Groups:
    • ALB security group allows 80/443 from internet
    • Instance security group allows traffic from ALB

Slow Response Times

Solutions:

  1. Check Aurora ACU Utilization:
    • Go to RDS Console → Your cluster
    • Click Monitoring tab
    • Check ServerlessDatabaseCapacity metric
  2. Increase Aurora Max Capacity:
    • Update stack parameter DBAuroraMaxACU
    • Recommend doubling current max
  3. Review CloudWatch Metrics:
    • EC2 CPU utilization
    • Aurora CPU utilization
    • EFS throughput
  4. Scale Out Instances:
    • Increase ASGDesiredCapacity
    • Or configure auto-scaling policies

Performance Issues

Need to Resize Instance

Symptoms:

  • High CPU utilization
  • Slow page loads
  • Out of memory errors

Solutions:

For Basic/Standard (Single Instance):

  1. Stop the instance
  2. Go to EC2 Console → Instances
  3. Select instance → Actions → Instance Settings → Change Instance Type
  4. Choose larger size (e.g., m8g.medium → m8g.large)
  5. Start instance (Elastic IP remains the same)

For Enterprise (Auto Scaling Group):

  1. Update CloudFormation stack
  2. Change InstanceType parameter
  3. Auto Scaling Group will perform rolling update
  4. Zero downtime during update

Increase Disk Space

Solutions:

  1. Modify EBS Volume: 
    # Get volume ID
aws ec2 describe-instances \
  --instance-ids i-xxxxx \
  --query 'Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.VolumeId'
   
# Increase volume size
aws ec2 modify-volume --volume-id vol-xxxxx --size 100
  2. Extend Filesystem: 
    # After volume modification
sudo growpart /dev/nvme0n1 1
sudo resize2fs /dev/nvme0n1p1
   
# Verify
df -h

Network Configuration Issues

VPC/Subnet Selection Problems

Symptoms:

  • Can’t select subnets in CloudFormation
  • Subnets not in dropdown

Solutions:

  1. Use Default VPC:
    • Leave VpcId and SubnetId blank
    • CloudFormation will auto-select
  2. Check Subnet Availability:
    • Go to VPC Console → Subnets
    • Verify subnets exist in your region
    • Check available IP addresses
  3. Enterprise Multi-AZ Requirements:
    • Need at least 2 public subnets (different AZs)
    • Need at least 2 private subnets (different AZs)
    • Check Availability Zone column in VPC console

Getting Help

Check Stack Events

Always start here:

  1. CloudFormation console
  2. Select your stack
  3. Events tab
  4. Sort by timestamp (newest first)
  5. Look for CREATE_FAILED or UPDATE_FAILED

Collect Diagnostic Information

Before contacting support:

  1. Stack Details:
    • Stack name
    • Region
    • CloudFormation Events tab (screenshot)
  2. Instance Logs: 
    # Create log bundle
sudo tar -czf koha-logs.tar.gz \
  /var/log/cloud-init*.log \
  /var/log/koha/library/*.log \
  /var/log/apache2/*.log
   
# Download via S3
aws s3 cp koha-logs.tar.gz s3://your-bucket/
  3. Configuration:
    • AMI ID
    • Instance type
    • Deployment tier

Contact Support

Email: support@kohasupport.com

Include:

  • Detailed problem description
  • Stack name and region
  • Error messages from Events tab
  • Steps you’ve already tried
  • Log files (if applicable)

Last Updated: December 2025