Troubleshooting

The errors you're most likely to hit, and the one-line fix for each.

Credentials & access

“No AWS credentials found”

Laminar uses the standard AWS chain. Configure one of:

aws configure
export AWS_PROFILE=myprofile
laminar deploy dev --profile myprofile

“Your AWS session token has expired” / InvalidClientTokenId

Your keys/SSO session expired or are wrong. Refresh SSO (aws sso login) or re-run aws configure, then retry.

AccessDenied on AssumeRole (cross-account)

The target role’s trust policy must allow your principal and match the ExternalId. Verify the ARN and pass the right id:

laminar deploy prod --assume-role-arn <arn> --external-id <id>

See Cloud & cross-account.

Deploy used the wrong region

Region resolves as --region → AWS_REGION → laminar.yml → us-east-1. Set it explicitly to be sure.

Lambda

Environment variables too large

AWS caps Lambda env at 4 KB (key+value). Laminar auto-offloads to SSM Parameter Store when you exceed it; the function loads them at runtime. To force it, set an ssm_prefix and use laminar env-push.

“handler must be in format module.function”

Set handler: correctly for your runtime (e.g. handler.app for Python, public/index.php for PHP/Laravel, a bootstrap for Go).

PHP/Laravel deploy fails on layers

PHP/Laravel need Bref layers. Add them under layers: for your region — see Runtimes.

Fargate / EC2

Service is running but targets are unhealthy

The ALB health check is failing. Confirm fargate.health_check path returns 200 and the container listens on fargate.port. laminar logs <stage> shows why.

Tasks can’t pull the image / no internet

Private subnets need a NAT gateway, or set fargate.assign_public_ip: true. With NAT, keep it false (more secure).

Partial deploy left resources behind

Run laminar destroy <stage> to clean up, then redeploy. (EC2 auto-terminates a failed new instance.)

Resources

S3 “bucket name is taken”

Bucket names are globally unique. Set an explicit storage.bucket in laminar.yml.

Database endpoint is blank

RDS/Aurora take a few minutes to become available. Re-run laminar databases list / info. Credentials are in Secrets Manager once created.

FIFO queue send fails

FIFO sends need a group id: laminar queues send <name> <body> --group-id g1.

Still stuck?

Open an issue on GitHub with the command, the error, and your laminar.yml (redact secrets).