{
  "id": "aws/s3-bucket-policy-invalid-principal",
  "signature": "An error occurred (MalformedPolicy) when calling the PutBucketPolicy operation: Invalid principal in policy",
  "signature_zh": "调用 PutBucketPolicy 操作时发生错误 (MalformedPolicy)：策略中的主体无效",
  "regex": "An error occurred \\(MalformedPolicy\\) when calling the PutBucketPolicy operation: Invalid principal in policy",
  "domain": "aws",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "The Principal element in the S3 bucket policy references an IAM ARN that does not exist or uses an unsupported format (e.g., 'AWS: *' instead of 'AWS: *' or a specific ARN).",
  "root_cause_type": "generic",
  "root_cause_zh": "S3 存储桶策略中的 Principal 元素引用了一个不存在的 IAM ARN，或使用了不支持的格式（例如，使用 'AWS: *' 而不是 'AWS: *' 或特定 ARN）。",
  "versions": [
    {
      "version": "AWS CLI 2.15.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS SDK for Python 1.34.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS SDK for JavaScript 3.600.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Adding a wildcard principal like 'Principal': 'AWS: *' with a typo (e.g., extra space) will still fail; the exact format 'AWS: *' is required.",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Using a principal ARN that is in a different AWS account without proper cross-account trust setup will cause this error.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Assuming the error is a syntax issue in the Effect or Action field, while the real problem is the Principal format.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Use the AWS CLI to test the policy: `aws s3api put-bucket-policy --bucket my-bucket --policy file://policy.json` and check the error message for the exact principal ARN that is invalid. Then correct it to a valid IAM user/role ARN (e.g., 'arn:aws:iam::123456789012:user/username').",
      "success_rate": 0.85,
      "how": "Use the AWS CLI to test the policy: `aws s3api put-bucket-policy --bucket my-bucket --policy file://policy.json` and check the error message for the exact principal ARN that is invalid. Then correct it to a valid IAM user/role ARN (e.g., 'arn:aws:iam::123456789012:user/username').",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using a service principal, ensure the format is 'Service': 's3.amazonaws.com' (or other service) instead of an ARN. Example: `\"Principal\": { \"Service\": \"cloudfront.amazonaws.com\" }`.",
      "success_rate": 0.9,
      "how": "If using a service principal, ensure the format is 'Service': 's3.amazonaws.com' (or other service) instead of an ARN. Example: `\"Principal\": { \"Service\": \"cloudfront.amazonaws.com\" }`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use the AWS Policy Simulator to validate the policy before applying it: https://policysim.aws.amazon.com/",
      "success_rate": 0.75,
      "how": "Use the AWS Policy Simulator to validate the policy before applying it: https://policysim.aws.amazon.com/",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用 AWS CLI 测试策略：`aws s3api put-bucket-policy --bucket my-bucket --policy file://policy.json` 并检查错误消息中无效的主体 ARN。然后将其更正为有效的 IAM 用户/角色 ARN（例如 'arn:aws:iam::123456789012:user/username'）。",
    "如果使用服务主体，请确保格式为 'Service': 's3.amazonaws.com'（或其他服务）而不是 ARN。例如：`\"Principal\": { \"Service\": \"cloudfront.amazonaws.com\" }`。",
    "在应用策略之前使用 AWS Policy Simulator 进行验证：https://policysim.aws.amazon.com/"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-actions.html",
  "official_doc_section": null,
  "error_code": "MalformedPolicy",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2023-06-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}