PolicyNotAttachable
AWS PolicyNotAttachable means the policy cannot be attached because service-role policies are attachable only to their service-linked roles (HTTP 400).
Last reviewed: May 4, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Policy Not Attachable Mean?
IAM rejected the policy attachment because that policy type is not attachable to the selected principal, so permission rollout stops until a compatible policy-principal pairing is used.
Common Causes
- -Policy is service-linked-role scoped and cannot attach to arbitrary principals.
- -Target role/user/group type is incompatible with the policy attachment rules.
- -Automation attempts to attach AWS-managed service-role policy to non-service-linked role.
- -Attachment workflow assumes policy portability across incompatible IAM entities.
How to Fix Policy Not Attachable
- 1Verify policy type and attach only to supported principal type.
- 2Use customer-managed policy when cross-role attachment is required.
- 3Inspect service-linked role requirements before attachment changes.
- 4Retry attachment with a policy-principal combination supported by IAM.
Step-by-Step Diagnosis for Policy Not Attachable
- 1Capture policy ARN and target principal type from failing request.
- 2Check IAM policy metadata and service-linked restrictions.
- 3Compare failing attachment path with a known supported IAM attachment pattern.
- 4Audit automation defaults that pick incompatible policy ARNs.
Policy Type and Principal Compatibility
- -Inspect policy metadata and attachability constraints (example: AWS managed service-role policy cannot attach to standard customer role).
- -Validate target principal class for attachment operation (example: workflow targets IAM user while policy is intended for service-linked role only).
Attachment Workflow Contract Checks
- -Audit policy-selection logic in automation catalogs (example: wildcard match selects non-attachable AWS managed policy ARN).
- -Verify create/update path chooses customer-managed fallback when attachability rules disallow target (example: generate equivalent custom policy and attach to role).
Decision Shortcut: Policy Type vs Target Principal
- -If the policy ARN path contains
service-role, verify it is intended for the matching service-linked role before attaching it elsewhere. - -If the target is a normal customer role, prefer a customer-managed policy or an AWS managed policy that is explicitly attachable to that principal type.
- -If the target entity is service-managed and immutable, investigate
UnmodifiableEntityrather than policy attachability alone.
Wrong Fix to Avoid
- -Do not copy permissions from a service-role policy into production manually without checking resource scope and conditions.
- -Do not retry attachment with the same policy-principal pair; IAM attachability rules are deterministic.
- -Do not treat all AWS managed policies as portable. Some are scoped to service-linked role workflows only.
Implementation Examples
POLICY_ARN=arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
ROLE_NAME=app-runtime-role
aws iam get-policy --policy-arn "$POLICY_ARN" \
--query 'Policy.{arn:Arn,path:Path,name:PolicyName,attachable:IsAttachable,attachments:AttachmentCount}'
aws iam get-role --role-name "$ROLE_NAME" \
--query 'Role.{arn:Arn,path:Path,service:AssumeRolePolicyDocument.Statement[0].Principal}'aws iam attach-role-policy \
--role-name app-runtime-role \
--policy-arn arn:aws:iam::111122223333:policy/app-runtime-least-privilegeIncident Timeline
16:10 UTC
Deployment selects a policy ARN from a catalog
Signal: Automation picks an AWS managed or service-role policy by name pattern and targets a role, group, or user.
Why it matters: The selected policy ARN and target principal type must be logged together; either side can make the pair invalid.
16:11 UTC
IAM rejects the attachment
Signal: AttachRolePolicy or related attachment call returns PolicyNotAttachable with a request ID.
Why it matters: The policy exists and the principal may exist; the failure is compatibility, not necessarily missing IAM objects.
16:18 UTC
Policy metadata reveals non-portable scope
Signal: The policy is a service-linked-role policy or otherwise not attachable to the chosen principal class.
Why it matters: Switch to the supported service-linked role path or create a customer-managed policy with the required least-privilege statements.
16:30 UTC
Pre-attach validation is added to the rollout
Signal: CI rejects incompatible policy-principal pairs before IAM API calls run.
Why it matters: This turns a deployment-time IAM failure into a catalog validation issue.
Seen in Production
Service-linked role policy is attached to incompatible principal
Frequency: common
Example: Automation attempts to attach service-role policy ARN to a standard IAM role.
Fix: Use compatible customer-managed policy or target the correct service-linked role.
Policy catalog lacks attachability metadata
Frequency: rare
Example: Deployment picks policy by name pattern and selects non-attachable policy type.
Fix: Store policy-type metadata and validate attachability before apply.
Wrong Fix vs Better Fix
Name-based policy selection vs attachability metadata
Wrong fix: Select policies by substring match and try to attach whichever ARN looks close to the desired service.
Better fix: Store policy type, attachability, allowed principal class, and service-linked role requirements in the policy catalog.
Why this is better: Automation can reject incompatible pairs before changing IAM and can explain which policy type is allowed.
Service-role policy cloning vs least-privilege custom policy
Wrong fix: Copy a service-role policy wholesale into a custom policy to bypass attachability.
Better fix: Create a customer-managed policy with only the required actions, resources, and conditions for the target role.
Why this is better: The target role gets the needed permission without importing service-managed assumptions or broad hidden scope.
Debugging Tools
- -IAM policy metadata inspection
- -Attachment target-type checks
- -AWS CLI --debug
- -CloudTrail IAM attachment events
How to Verify the Fix
- -Retry the attachment and confirm PolicyNotAttachable is no longer returned.
- -Validate policy is attached only to compatible principal types.
- -Ensure downstream role workflows operate with expected policy bindings.
How to Prevent Recurrence
- -Classify policy ARNs by attachability constraints in automation.
- -Add pre-attach validation for policy type versus principal type.
- -Document service-linked role policy restrictions in IAM runbooks.
Pro Tip
- -pre-classify policy ARNs by attachability (AWS managed, customer managed, service-role policy) and reject invalid pairings before API calls.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.