How to read an AWS AccessDenied message, find which policy type blocked the call, test the fix with the IAM policy simulator, and avoid the ARN, KMS and role mix-ups behind most of these errors.

Every AWS API call is checked against IAM policies, and when nothing allows it the call fails with "User: arn:... is not authorized to perform". The message names the principal, the action, the resource and usually the reason, which is enough to find the fix.
This guide walks through reading the message, finding the blocking policy and testing the fix.
A typical message from S3 through the AWS CLI looks like this:
The principal is an assumed role, billing-task, with a session name after the last slash, so the policy to inspect is on the role and not on any user. The action is s3:PutObject, the resource is an object ARN, and the reason says no identity-based policy allowed it. AWS added these reason phrases to most services, and for a service that leaves the reason out, you check each policy type in turn.
IAM evaluates every policy type that applies, and an explicit Deny in any of them wins over every Allow, as the policy evaluation logic describes. Within one account, an Allow in either the identity policy or the resource policy is enough, while a cross-account call needs both. SCPs and permissions boundaries never grant anything, they only cap what other policies allow, which is why a role with s3:* can still be denied by an organization SCP that blocks a Region.
Most "it has the permission" cases come down to one of these:
s3:ListBucket apply to arn:aws:s3:::acme-invoices, while object actions apply to arn:aws:s3:::acme-invoices/*, and a policy with only one of them fails the other half.kms:GenerateDataKey or kms:Decrypt rather than the S3 action.aws:SourceVpce or s3:x-amz-server-side-encryption does not match the request.For this example, the fix is an identity policy statement on billing-task that matches the object ARN:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject"],
"Resource": "arn:aws:s3:::acme-invoices/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::acme-invoices"
}
]
}
Confirm the principal with aws sts get-caller-identity in the failing environment, then ask the IAM policy simulator whether the role may perform the action on that exact resource:
implicitDeny means nothing allowed it, and explicitDeny means a Deny matched, with MatchedStatements naming the statement. The simulator evaluates identity policies, permissions boundaries and SCPs, without showing which SCP statement matched. It does not fetch resource policies, and for roles it cannot simulate them at all, so a bucket policy deny can still surprise you.
Services such as EC2 return an encoded failure message instead of the plain text, which aws sts decode-authorization-message turns into JSON. In CloudTrail, the failed call appears with errorCode set to AccessDenied or Client.UnauthorizedOperation, along with the full principal and request parameters.
The errors cluster where policies are written by hand far from the code that needs them: a new S3 prefix, a second queue or an encryption change lands in the application, and the matching IAM change lands later, or in a different repository. Policies generated from the same definition as the resource, and integration tests that run with the deployed role in a staging account, catch most of them before production.
Encore brings infrastructure from code: a service declares the bucket or Pub/Sub topic it uses, Encore creates the resources from those declarations, and Encore provisions an IAM role for the service. The policy document from the previous section is not something you write or keep in sync with the code.

Run in your terminal to get started locally.
// invoices/invoices.ts
import { api } from "encore.dev/api";
import { Topic } from "encore.dev/pubsub";
import { Bucket } from "encore.dev/storage/objects";
// Declared resources: the service's access to them comes from this code,
// not from a policy document someone has to keep in sync.
export const invoicePdfs = new Bucket("invoice-pdfs", { versioned: false });
export interface InvoiceIssued {
invoiceId: string;
key: string;
}
export const invoiceIssued = new Topic<InvoiceIssued>("invoice-issued", {
deliveryGuarantee: "at-least-once",
});
interface IssueRequest {
invoiceId: string;
pdfBase64: string;
}
export const issue = api(
{ expose: false, method: "POST", path: "/invoices/:invoiceId/issue" },
async ({ invoiceId, pdfBase64 }: IssueRequest): Promise<{ key: string }> => {
const key = `${invoiceId}.pdf`;
await invoicePdfs.upload(key, Buffer.from(pdfBase64, "base64"), {
contentType: "application/pdf",
});
await invoiceIssued.publish({ invoiceId, key });
return { key };
},
);
With an encore.service.ts file in invoices/, encore run serves the bucket from local storage and runs the topic on a local broker, so the endpoint works on a laptop with no AWS profile at all. On deploy to your own AWS account, Encore creates the S3 bucket and the SNS topic, and Encore provisions an IAM role for the service.
This is also where coding agents get into trouble with IAM: an agent that adds an S3 call to a handler has no reliable way to know the deployed role is missing s3:PutObject until production says so. With the bucket declared in the same file, the agent's change carries its own infrastructure, and it can run the code locally before anything is deployed.
Best fit: Teams whose AccessDenied errors come from application code and IAM policies drifting apart, and who want resources and access defined by the same code in their own AWS account.
The principal named in the message, a user or an assumed role, made an API call that IAM policy evaluation denied. The message names the action and the resource, and usually ends with the reason, such as no identity-based policy allowing the action or an explicit deny in a service control policy.
The usual causes are a resource ARN that does not match, such as arn:aws:s3:::bucket instead of arn:aws:s3:::bucket/* for object actions, a different role than you think, an explicit deny in an SCP or permissions boundary, or a KMS key policy that does not allow the role to use the key.
Run aws sts get-caller-identity in the same environment, or call the STS GetCallerIdentity API from the SDK. The Arn in the response shows the assumed role and session name, which is the principal AWS evaluates.
Some services, such as EC2, return an encoded message. Run aws sts decode-authorization-message --encoded-message with the text, using a principal allowed to call sts:DecodeAuthorizationMessage, and the decoded JSON shows the matched statements and the context of the request. Encore apps that only use declared resources get their access from the code, since Encore provisions an IAM role for the service.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.