Introduction

The AWS IAM error saying a request has a prohibited field usually means the payload includes attributes that CreateRole does not accept. This often happens when developers copy output from GetRole or console exports and try to submit it directly as create input. The fix is to send only allowed create parameters.

Why the Error Appears

IAM APIs have strict request schemas. Fields present in read responses, such as generated identifiers or metadata, cannot be reused in create calls.

Typical mistake pattern:

• fetch role definition
• copy full JSON object
• send same JSON into create endpoint

Response only fields like RoleId, Arn, and CreateDate are prohibited during create.

Valid create-role CLI Usage

Use only supported options such as role name and trust policy.

1aws iam create-role \
2  --role-name AppReadRole \
3  --assume-role-policy-document file://trust-policy.json \
4  --description "Role for app read access"

Trust policy file example:

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Principal": {
7        "Service": "ec2.amazonaws.com"
8      },
9      "Action": "sts:AssumeRole"
10    }
11  ]
12}

Then attach permissions separately:

aws iam attach-role-policy \
  --role-name AppReadRole \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

Common Source of Prohibited Fields

Developers frequently paste a role object into Infrastructure as Code or SDK requests with unsupported keys.

Example problematic object fields:

• Arn
• RoleId
• CreateDate
• RoleLastUsed

These belong to response payloads and must be removed.

SDK Example with Allowed Fields

Python boto3 example:

1import boto3
2
3iam = boto3.client("iam")
4
5assume_role_policy = """
6{
7  "Version": "2012-10-17",
8  "Statement": [
9    {
10      "Effect": "Allow",
11      "Principal": {"Service": "lambda.amazonaws.com"},
12      "Action": "sts:AssumeRole"
13    }
14  ]
15}
16"""
17
18resp = iam.create_role(
19    RoleName="LambdaExecRoleExample",
20    AssumeRolePolicyDocument=assume_role_policy,
21    Description="Execution role for Lambda"
22)
23
24print(resp["Role"]["RoleName"])

Provide only create parameters documented for the API.

CloudFormation and Terraform Context

In IaC tools, this error can surface when resource blocks include read only attributes from state exports or copied API output. Keep templates declarative and limited to resource input fields.

CloudFormation role resource should include trust policy and optional policy attachments, not generated identifiers. Terraform role blocks should likewise omit response only attributes.

Debugging Workflow

When you hit prohibited field errors:

1. Turn on request logging in SDK or CLI debug mode.
2. Compare request keys against CreateRole documentation.
3. Remove response only metadata fields.
4. Retry with minimal request body.
5. Add fields back only when confirmed supported.

CLI debug mode example:

aws iam create-role ... --debug

This quickly reveals which field triggered validation.

Validate Trust Policy Separately

Even after prohibited fields are removed, CreateRole can still fail if trust policy JSON is malformed or principal values are wrong. Validate trust policy with JSON linting and a staged create call in a non production account. Separating schema cleanup from trust policy validation shortens debugging cycles and clarifies whether failure comes from request shape or IAM policy semantics.

Also keep IAM API versions consistent across tooling in your delivery pipeline.

Common Pitfalls

• Copying full GetRole output and treating it as valid CreateRole input.
• Supplying generated fields such as RoleId or Arn in create requests.
• Mixing trust policy document with permission policy expectations.
• Forgetting JSON escaping or file URI prefix when passing trust policy through CLI.
• Debugging IAM permissions first when the root cause is request schema validation.

Summary

• Prohibited field errors come from unsupported keys in CreateRole requests.
• Use only documented create parameters such as role name and trust policy.
• Do not reuse response metadata fields in create payloads.
• Validate request shape with CLI debug or SDK logging.
• Keep IaC definitions limited to input schema fields.