Troubleshooting

Solutions for common AWS connection issues.

Connection Status: Invalid

Your connection shows Invalid status after validation.

Cause 1: Trust Policy Misconfigured

The IAM role's trust policy doesn't allow Orkestia to assume it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::856022192189:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }
  ]
}

Cause 2: Wrong External ID

The External ID in your trust policy doesn't match.

Cause 3: Wrong Orkestia Account ID

The trusted AWS account ID is incorrect.

Verify the Principal in your trust policy uses:

arn:aws:iam::856022192189:root

Cause 4: Role Was Deleted

The IAM role no longer exists in AWS.

1. Check if the role exists in AWS IAM Console
2. If deleted, create a new role following Setup Methods
3. Update the connection with the new Role ARN

Missing Permissions

Validation shows Missing Permissions errors.

Symptoms

• Specific permissions listed as missing
• Connection may show as Invalid or have warnings

Solution

1. Open the IAM role in AWS Console
2. Check the attached policies
3. Add the missing permissions

Required base permissions:

• sts:GetCallerIdentity
• s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject
• cloudfront:GetDistribution, cloudfront:CreateInvalidation

With Route53:

• route53:ListHostedZones
• route53:ChangeResourceRecordSets
• route53:GetChange

Quick Fix

Replace your policy with the complete policy from the Orkestia wizard:

1. In Orkestia, click Add Connection
2. Navigate to Step 4 (Setup Instructions)
3. Copy the Permission Policy
4. Replace your existing policy in AWS

Connection In Use Error

You can't delete a connection because it's in use.

Symptoms

Error message: "Cannot delete connection: This connection is currently in use by X sites."

Solution

1. Identify which sites are using this connection
2. For each site:
   • Go to Site Settings
   • Change the AWS connection to a different one
3. Return and delete the original connection

Alternative: Create New Connection First

1. Create a new AWS connection
2. Update all sites to use the new connection
3. Delete the old connection

Validation Keeps Failing

Repeated validation attempts fail.

Check 1: Role Exists

Verify the IAM role still exists:

aws iam get-role --role-name YOUR_ROLE_NAME

If you get "NoSuchEntity", the role was deleted.

Check 2: Trust Policy

Ensure the trust policy allows AssumeRole from Orkestia:

aws iam get-role --role-name YOUR_ROLE_NAME --query 'Role.AssumeRolePolicyDocument'

Verify it contains the correct Principal and External ID.

Check 3: Permission Boundaries

Check if there's a permission boundary blocking access:

aws iam get-role --role-name YOUR_ROLE_NAME --query 'Role.PermissionsBoundary'

If a boundary exists, ensure it allows the required actions.

Check 4: Service Control Policies (SCPs)

If using AWS Organizations, check if SCPs are blocking:

1. Go to AWS Organizations console
2. Check policies attached to your account's OU
3. Ensure they don't deny the required actions

Check 5: AWS Region Issues

Ensure the IAM role is in a supported region. IAM is global, but some policies may reference regional resources.

Access Denied Errors

Deployments fail with "Access Denied" errors.

For S3 Errors

Check the S3 bucket policy isn't blocking access:

aws s3api get-bucket-policy --bucket YOUR_BUCKET_NAME

Ensure the IAM role's permissions include the bucket.

For CloudFront Errors

CloudFront requires * as the resource. Verify your policy includes:

{
  "Action": [
    "cloudfront:CreateDistribution",
    "cloudfront:GetDistribution",
    "cloudfront:UpdateDistribution"
  ],
  "Resource": "*"
}

ARN Validation Errors

The Role ARN doesn't pass validation.

Invalid Format

ARN must follow this format:

arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME

Common mistakes:

• Missing arn:aws:iam:: prefix
• Wrong number of colons
• Spaces in the ARN
• Using instance profile ARN instead of role ARN

Copy Error

When copying the ARN, ensure you:

• Copy the complete ARN
• Don't include extra whitespace
• Use the Role ARN, not the Instance Profile ARN

Role ARN vs Instance Profile

Correct (Role ARN):

arn:aws:iam::123456789012:role/OrkestiaRole

Incorrect (Instance Profile ARN):

arn:aws:iam::123456789012:instance-profile/OrkestiaRole

To find the correct ARN:

1. Open IAM Console > Roles
2. Click your role
3. Copy the ARN from the summary section

Suspended Connection

Your connection shows Suspended status.

Cause

Too many consecutive validation failures. This prevents excessive API calls to AWS.

Solution

1. Fix the underlying issue (usually trust policy or permissions)
2. Click Validate to re-check the connection
3. If validation passes, status will change to Active

Still Having Issues?

If you've tried the above solutions and still have problems:

Quick Reference

Related