Troubleshooting

Common issues and solutions for Serverless CMS deployment and operation.

On This Page

Deployment Errors

Certificate Validation Timeout

Symptom: Deployment hangs or times out during SSL certificate validation.

Cause: DNS records haven't propagated or Route 53 hosted zone is misconfigured.

Solution:

  1. Verify Route 53 hosted zone exists: 
    aws route53 list-hosted-zones --profile cms-deploy
  2. Check nameservers are correctly configured: 
    dig NS example.com +short
  3. Wait for DNS propagation (up to 48 hours)
  4. Retry deployment after DNS propagates

CloudFormation Stack Creation Failed

Symptom: Deployment fails with CloudFormation errors.

Solution:

# View CloudFormation stack events
aws cloudformation describe-stack-events \
  --stack-name serverless-cms \
  --region eu-west-2 \
  --profile cms-deploy

# Check stack status
aws cloudformation describe-stacks \
  --stack-name serverless-cms \
  --region eu-west-2 \
  --profile cms-deploy

Look for ResourceStatusReason in the output for specific error messages.

Build Failures

Symptom: mvn clean package fails.

Common causes:

  • Node.js not installed: Install Node.js 22.x
  • npm dependencies fail: Delete node_modules and retry
  • Maven version too old: Upgrade to Maven 3.9+
# Clean and rebuild
rm -rf node_modules target
mvn clean package

AWS Permission Issues

Access Denied Errors

Symptom: Deployment fails with "Access Denied" or "UnauthorizedOperation" errors.

Solution:

  1. Verify IAM user has required policies: 
    aws iam list-attached-user-policies \
  --user-name serverless-cms-deployer \
  --profile cms-deploy
  2. Check policy permissions match requirements in AWS Setup
  3. Verify AWS CLI profile is configured: 
    aws sts get-caller-identity --profile cms-deploy

IAM Role Creation Failed

Symptom: Cannot create Lambda execution roles, e.g. User: arn:aws:iam::<account>:user/serverless-cms is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::<account>:role/publisher-exec-role.

Solution: Ensure the IAM user has iam:CreateRole, iam:PassRole and iam:UpdateAssumeRolePolicy permissions. The last is required so an existing execution role's trust policy can be refreshed during redeployment.

Note: Execution roles are named <function-name>-exec-role (for example publisher-exec-role) and do not include the serverless-cms prefix. Make sure the Resource list of your IAM policy covers these role names, e.g. add arn:aws:iam::*:role/*-exec-role. A policy scoped only to arn:aws:iam::*:role/*serverless-cms* will fail with a 403 on iam:CreateRole.

EventBridge Scheduler Cannot Assume Role

Symptom: Deployment or a scheduled action fails with ValidationException: The execution role you provide must allow AWS EventBridge Scheduler to assume the role.

Solution: The Lambda execution role's trust policy must allow both lambda.amazonaws.com and scheduler.amazonaws.com to assume it. Redeploy with an IAM user that has iam:UpdateAssumeRolePolicy so the trust policy of existing roles is refreshed automatically.

S3 Bucket Access Denied

Symptom: Cannot upload to S3 buckets.

Solution:

# Check bucket policy
aws s3api get-bucket-policy \
  --bucket serverless-cms-component-store \
  --profile cms-deploy

# Test bucket access
aws s3 ls s3://serverless-cms-component-store --profile cms-deploy

Domain and DNS Issues

Admin Tool Not Accessible

Symptom: Cannot access https://admin.example.com

Solution:

  1. Check DNS resolution: 
    dig admin.example.com +short
  2. Verify CloudFront distribution is deployed: 
    aws cloudfront list-distributions \
  --query "DistributionList.Items[?Comment=='Admin_Tool']" \
  --profile cms-deploy
  3. Check Route 53 records: 
    aws route53 list-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --profile cms-deploy
  4. Wait for DNS propagation (5-30 minutes)

SSL Certificate Errors

Symptom: Browser shows "Your connection is not private" or certificate errors.

Solution:

  1. Check certificate status: 
    aws acm list-certificates --region us-east-1 --profile cms-deploy
  2. Verify certificate is issued (not pending validation)
  3. Check certificate is attached to CloudFront distribution
  4. Clear browser cache and retry

Subdomain Not Resolving

Symptom: Site subdomain (e.g., blog.example.com) doesn't resolve.

Solution:

  1. Verify site was created successfully in Admin Tool
  2. Check Route 53 for A/CNAME record
  3. Publish at least one page to trigger DNS record creation
  4. Wait for DNS propagation

Lambda Function Errors

Function Timeout

Symptom: Lambda functions timeout (30-60 seconds).

Solution:

  1. Check CloudWatch logs: 
    aws logs tail /aws/lambda/serverless-cms-cms-functions-sites-create \
  --follow \
  --region eu-west-2 \
  --profile cms-deploy
  2. Increase timeout in deployment profile (see Deployment)
  3. Optimize function code or database queries

Out of Memory Errors

Symptom: Lambda functions fail with "Process exited before completing request".

Solution:

  1. Check memory usage in CloudWatch metrics
  2. Increase Lambda memory allocation in pom.xml: 
    <lambda.memory>1024</lambda.memory>
  3. Redeploy with updated configuration

Module Not Found Errors

Symptom: Lambda functions fail with "Cannot find module" errors.

Solution:

  1. Verify package.json includes all dependencies
  2. Rebuild Lambda functions: 
    cd functions/cms-functions
rm -rf node_modules
npm install
cd ../..
mvn clean package
  3. Redeploy

DynamoDB Issues

Throttling Errors

Symptom: "ProvisionedThroughputExceededException" errors.

Solution:

  1. Check DynamoDB metrics in CloudWatch
  2. DynamoDB uses on-demand billing by default (auto-scales)
  3. If using provisioned capacity, increase RCU/WCU

Item Not Found

Symptom: Cannot retrieve items from DynamoDB.

Solution:

# Scan table to verify data exists
aws dynamodb scan \
  --table-name serverless-cms-content-store \
  --limit 10 \
  --region eu-west-2 \
  --profile cms-deploy

# Check table status
aws dynamodb describe-table \
  --table-name serverless-cms-content-store \
  --region eu-west-2 \
  --profile cms-deploy

Conditional Check Failed

Symptom: Updates fail with "ConditionalCheckFailedException".

Cause: Optimistic locking or concurrent updates.

Solution: Retry the operation. The CMS handles this automatically for most operations.

S3 Access Issues

403 Forbidden on Published Pages

Symptom: Published pages return 403 errors.

Solution:

  1. Check S3 bucket policy allows CloudFront access
  2. Verify Origin Access Control (OAC) is configured
  3. Check file was uploaded successfully: 
    aws s3 ls s3://serverless-cms-publish-store/blog/ \
  --recursive \
  --profile cms-deploy

Component Upload Fails

Symptom: Cannot upload component ZIP files.

Solution:

  1. Verify ZIP file is under 10 MB
  2. Check ZIP structure matches requirements
  3. Verify S3 bucket exists and is accessible
  4. Check CloudWatch logs for validation errors

Authentication Issues

Cannot Login to Admin Tool

Symptom: Login fails with "Incorrect username or password".

Solution:

  1. Verify user exists in Cognito: 
    aws cognito-idp list-users \
  --user-pool-id YOUR_USER_POOL_ID \
  --region eu-west-2 \
  --profile cms-deploy
  2. Reset password: 
    aws cognito-idp admin-set-user-password \
  --user-pool-id YOUR_USER_POOL_ID \
  --username user@example.com \
  --password "NewPassword123!" \
  --permanent \
  --region eu-west-2 \
  --profile cms-deploy

JWT Token Expired

Symptom: Logged out unexpectedly or "Token expired" errors.

Solution: Refresh the page to get a new token. The Admin Tool automatically refreshes tokens when possible.

Insufficient Permissions

Symptom: "You don't have permission to perform this action" errors.

Solution:

  1. Check user's group memberships: 
    aws cognito-idp admin-list-groups-for-user \
  --user-pool-id YOUR_USER_POOL_ID \
  --username user@example.com \
  --region eu-west-2 \
  --profile cms-deploy
  2. Add user to appropriate groups via Admin Tool or AWS CLI

Debugging Tools

CloudWatch Logs

View Lambda function logs:

# List log groups
aws logs describe-log-groups \
  --log-group-name-prefix "/aws/lambda/serverless-cms" \
  --region eu-west-2 \
  --profile cms-deploy

# Tail logs in real-time
aws logs tail /aws/lambda/serverless-cms-cms-functions-sites-create \
  --follow \
  --region eu-west-2 \
  --profile cms-deploy

# Search logs
aws logs filter-log-events \
  --log-group-name /aws/lambda/serverless-cms-cms-functions-sites-create \
  --filter-pattern "ERROR" \
  --region eu-west-2 \
  --profile cms-deploy

CloudWatch Metrics

Monitor Lambda performance:

# Get Lambda invocation count
aws cloudwatch get-metric-statistics \
  --namespace AWS/Lambda \
  --metric-name Invocations \
  --dimensions Name=FunctionName,Value=serverless-cms-cms-functions-sites-create \
  --start-time 2024-01-15T00:00:00Z \
  --end-time 2024-01-15T23:59:59Z \
  --period 3600 \
  --statistics Sum \
  --region eu-west-2 \
  --profile cms-deploy

X-Ray Tracing

Enable X-Ray for detailed request tracing:

  1. Enable X-Ray in Lambda function configuration
  2. View traces in AWS X-Ray console
  3. Analyze performance bottlenecks

API Gateway Logs

Enable CloudWatch logs for API Gateway:

  1. Go to API Gateway console
  2. Select your API
  3. Go to Stages → Logs/Tracing
  4. Enable CloudWatch Logs
  5. Set log level to INFO or ERROR

Getting Help

If you're still experiencing issues:

  • Check AWS Service Health: status.aws.amazon.com
  • Review CloudWatch Logs: Look for specific error messages
  • Check AWS Forums: Search for similar issues
  • Contact Support: Open an AWS support ticket if needed
Tip: When reporting issues, include CloudWatch log excerpts, error messages, and steps to reproduce the problem.