Troubleshooting

Common Errors

Error	Cause	Solution
`BucketAlreadyExists`	Bucket name taken globally	Use unique name with random suffix
`AccessDenied`	Insufficient IAM permissions	Check AWS permissions
`Build directory not found`	Build files missing	Run `npm run build` first
`Credentials not found`	AWS not configured	Run `aws configure`
`CertificateNotFound`	ACM in wrong region	Use `us-east-1` for certificates

AWS Credentials

bash

# Configure credentials
aws configure

# Or use environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

S3 Bucket Name

Bucket names must be globally unique:

typescript

s3: {
  bucketName: 'my-site-abc123', // Add random suffix
}

IAM Permissions

Required permissions:

json

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:*",
      "cloudfront:*",
      "acm:*",
      "route53:*"
    ],
    "Resource": "*"
  }]
}

CloudFront

First deployment takes 15-30 minutes
Check status: npx scf-deploy status
ACM certificates must be in us-east-1

TTL Settings Not Working (v2.0.0+)

Cause: TTL settings (defaultTTL, maxTTL, minTTL) were removed in v2.0.0.

Solution:

Remove TTL fields from your scf.config.ts
TTL is now managed automatically by AWS Managed Cache Policy (CachingOptimized)
If you need custom TTL values, configure them directly in AWS Console

typescript

// Remove these options in v2.0.0+
cloudfront: {
  defaultTTL: 3600,  // ❌ Remove
  maxTTL: 86400,     // ❌ Remove
  minTTL: 0,         // ❌ Remove
}

See Migration from v1.x for details.

Config File Not Found

bash

# Specify config path
npx scf-deploy deploy --config ./path/to/scf.config.ts

Getting Help

Search GitHub Issues
Create new issue with:
- Error message
- Steps to reproduce
- Environment (Node.js version, OS)