PacketSensei

AWS `UnauthorizedOperation`: What It Means and How to Fix It

PacketSensei

UnauthorizedOperation is the EC2 API telling you that IAM evaluated your request and denied it. It comes from EC2, and the message reads:

You are not authorized to perform this operation.

If you are here mid-incident, skip to how to tell which cause you have — the command there narrows it down faster than reading the list.

Quick reference
Error UnauthorizedOperation
Service EC2
Message You are not authorized to perform this operation.
Most common cause The IAM policy does not allow the action

What it actually means

EC2 returns UnauthorizedOperation when the caller’s identity is valid but IAM did not allow the action. It is an authorisation failure, not an authentication one — your credentials worked, and the policy evaluation said no.

The message is deliberately vague about why, because telling an unauthorised caller which permission they lack is itself an information leak. The encoded blob that sometimes accompanies it is the detail, and you can decode it.

Why it happens

Ranked by how often each one turns out to be the answer.

# Cause Fix
1 The IAM policy does not allow the action Add the specific action. EC2 action names do not always match the CLI command — aws ec2 describe-instances needs ec2:DescribeInstances, but aws ec2 run-instances needs ec2:RunInstances plus permissions on every resource it touches: the AMI, the subnet, the security groups, the key pair, and any volume being created.
2 A resource-level condition does not match Policies that scope by tag, region, or VPC deny anything outside the scope. aws:RequestedRegion, ec2:Vpc, and aws:ResourceTag conditions are the usual ones. Decode the message to see which condition failed.
3 A Service Control Policy at the organisation level denies it SCPs are invisible from inside the account — the IAM policy simulator in the account will say “allowed” while the call still fails. Check with an organisation admin, or use the simulator from the management account.
4 A permissions boundary caps the role A boundary limits the maximum permissions a role can have regardless of what its policy grants. Both must allow the action.
5 iam:PassRole is missing Launching an instance with an instance profile, or creating almost anything that assumes a role, requires iam:PassRole on that role in addition to the service action. This is the single most commonly missed permission in AWS.

How to tell which one you have

The error usually carries an encoded authorisation message. Decode it — it names the failing action, the principal, and the condition that did not match:

aws sts decode-authorization-message \
  --encoded-message <the-long-base64-blob> \
  --query DecodedMessage --output text | python3 -m json.tool

Decoding requires sts:DecodeAuthorizationMessage, which is worth granting to every engineer — it turns an opaque denial into a specific one.

To see the same thing before making the call, use a dry run:

aws ec2 run-instances --dry-run --image-id ami-0123456789abcdef0 \
  --instance-type t3.micro

A successful dry run returns DryRunOperation; a failure returns UnauthorizedOperation without launching anything.

CloudTrail records the denial with the full request context:

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=RunInstances \
  --max-results 5 --query 'Events[].CloudTrailEvent' --output text \
  | python3 -m json.tool | grep -A3 errorCode

Preventing it

Grant sts:DecodeAuthorizationMessage broadly — it exposes nothing an authorised caller could not already discover, and it removes a debugging round trip.

Where a role runs automation, test it with the IAM policy simulator in CI rather than discovering the gap during a deployment. And be explicit about iam:PassRole: write it into the policy at the same time as the service action, scoped to the specific role ARN rather than *.

Quota codes, limits and behaviour on this page were last checked against AWS documentation on 2026-08-22. AWS changes these; if something here does not match what you are seeing, trust the console and tell us.