How to fix UnauthorizedOperation in Terraform

Run Terraform with debug logging enabled to see the exact AWS API call and error details:

TF_LOG=debug terraform apply -target=aws_resource_type.name 2>&1 | tee terraform-debug.log

The -target flag reduces output volume by focusing on a single resource. Search the debug log for "Error:", "denied", or "UnauthorizedOperation" to find the specific AWS action (e.g., ec2:RunInstances, iam:PassRole, rds:CreateDBInstance).

If the error includes an "Encoded authorization failure message" with a long random-looking string, decode it with the AWS CLI to see which permission is missing:

aws sts decode-authorization-message --encoded-message 'COPY_THE_LONG_STRING_FROM_ERROR' --query DecodedMessage --output text

This reveals the exact IAM action that failed, such as "ec2:DescribeTags" or "iam:PassRole".

Add the required IAM action to your user or role's policy. For example, if the error indicates missing ec2:RunInstances permission:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2:RunInstances",
      "Resource": "*"
    }
  ]
}

Follow the principle of least privilege by restricting resources with specific ARNs instead of "*" where possible.

Check that Terraform is using the correct AWS profile and credentials:

# View current AWS profile
echo $AWS_PROFILE

# List available profiles
aws configure list-profiles

# Test credentials for the profile
aws sts get-caller-identity --profile your-profile

Ensure your Terraform AWS provider configuration matches the profile with proper permissions:

provider "aws" {
  region  = "us-east-1"
  profile = "your-profile"
}

If you're in an AWS Organization or have permission boundaries configured, verify they don't block the action:

For Organizations SCPs:
- Log in with admin credentials and check the IAM service for applied SCPs
- SCPs are restrictive policies applied at the organization or account level
- Contact your organization administrator if your required action is blocked

For permission boundaries:
- Check the IAM user or role details for attached permission boundaries
- Boundaries override explicit Allow statements, so they must grant the action
- Request your administrator to update the boundary policy if needed

The AWS IAM Policy Simulator can test if a policy allows an action without applying changes.

If the error started after upgrading your Terraform AWS provider, check the release notes for new required permissions:

# Check your current provider version
terraform version

# View provider release notes
# https://github.com/hashicorp/terraform-provider-aws/releases

Provider updates sometimes add new IAM actions to existing resources. Update your IAM policies to include these newly required actions.