# Troubleshooting AWS Errors

When Scanner validates your AWS infrastructure, it checks both the configuration of your S3 buckets and your IAM permissions. This page helps you understand and resolve the errors displayed in Scanner's error UI.

## Error Types

Errors are organized into two main categories:

### Configuration Errors

Configuration errors occur when Scanner's resources are not properly set up in AWS. These typically indicate missing or incorrectly configured S3 buckets and their settings.

**bucket\_presence** - Error calling `head-bucket`: `NoSuchBucket`

* **Cause**: The S3 bucket does not exist
* **Solution**:
  1. Verify the bucket name you provided in Scanner is correct (no typos, exact spelling)
  2. Ensure the bucket exists in your AWS account
  3. Check that the bucket is in the same AWS account linked to Scanner

**region** - Error calling `head-bucket`: "Bucket is in the region `X` instead of the expected `Y`"

* **Cause**: The bucket exists but is in a different AWS region than expected
* **Solution**:
  1. Check the actual region of your S3 bucket in the AWS Console
  2. Update Scanner's configuration to point to the correct region, or
  3. Create a new bucket in the expected region

**event\_notification\_presence** - Bucket does not have EventBridge notifications enabled

* **Cause**: The S3 log files bucket is not configured to send object-created events to AWS EventBridge
* **Solution**:
  1. Enable EventBridge notifications on your S3 log files bucket
  2. Ensure an EventBridge rule exists in the same region that forwards S3 object-created events to Scanner's event bus
  3. See the [CloudFormation](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/aws-cloudformation), [Terraform](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform), or [manual setup](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/manual-setup-aws-cloudshell) guides for how to configure this

### Permission Errors

Permission errors occur when the Scanner IAM role lacks the necessary permissions to access or manipulate AWS resources. These indicate either missing IAM policy statements or incorrect policy configuration.

**head\_bucket** - Error calling `head-bucket`: `NoSuchBucket` or `AccessDenied`

* **Cause (NoSuchBucket)**: The bucket does not exist or is not in the expected region
* **Cause (AccessDenied)**: The Scanner IAM role lacks permission to access the bucket
* **Solution**:
  1. If `NoSuchBucket`: Verify the bucket exists and is in the correct region (see Configuration Errors above)
  2. If `AccessDenied`: Ensure your Scanner IAM role policy includes `s3:ListBucket` permission for this bucket

**get\_bucket\_location** - Not checked or Error calling `get-bucket-location`: `AccessDenied`

* **Cause (Not checked)**: Skipped because bucket presence wasn't confirmed
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetBucketLocation` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetBucketLocation` for the bucket resources

**list\_objects\_v2** - Not checked or Error calling `list-objects-v2`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:ListBucket` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:ListBucket` for the bucket ARN (e.g., `arn:aws:s3:::your-bucket-name`)

**head\_object** - Not checked or Error calling `head-object`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetObject` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetObject` for the bucket objects ARN (e.g., `arn:aws:s3:::your-bucket-name/*`)

**get\_object** - Not checked or Error calling `get-object`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetObject` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetObject` for the bucket objects ARN (e.g., `arn:aws:s3:::your-bucket-name/*`)

**put\_object** - Not checked or Error calling `put-object`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:PutObject` permission (needed for writing index files)
* **Solution**: Ensure your Scanner IAM role policy includes `s3:PutObject` for the index bucket objects ARN

**delete\_object** - Not checked or Error calling `delete-object`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:DeleteObject` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:DeleteObject` for the relevant bucket objects ARN

**get\_object\_tagging** - Not checked or Error calling `get-object-tagging`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetObjectTagging` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetObjectTagging` for the bucket objects ARN

**put\_object\_tagging** - Not checked or Error calling `put-object-tagging`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:PutObjectTagging` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:PutObjectTagging` for the bucket objects ARN

**delete\_object\_tagging** - Not checked or Error calling `delete-object-tagging`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:DeleteObjectTagging` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:DeleteObjectTagging` for the bucket objects ARN

**get\_bucket\_notification\_configuration** - Not checked or Error calling `get-bucket-notification-configuration`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetBucketNotification` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetBucketNotification` for the bucket ARN

**get\_bucket\_lifecycle\_configuration** - Not checked or Error calling `get-bucket-lifecycle-configuration`: `AccessDenied`

* **Cause (Not checked)**: Permission check hasn't run yet or encountered a service error
* **Cause (AccessDenied)**: The Scanner IAM role lacks `s3:GetLifecycleConfiguration` permission
* **Solution**: Ensure your Scanner IAM role policy includes `s3:GetLifecycleConfiguration` for the bucket ARN

## Understanding the Scanner IAM Policy

The Scanner IAM role requires different permissions depending on the type of bucket:

* **Log buckets** (buckets you want Scanner to index): Read-only permissions (`s3:GetBucketLocation`, `s3:ListBucket`, `s3:GetObject`, `s3:GetObjectTagging`, `s3:GetBucketNotification`)
* **Index bucket** (Scanner's dedicated bucket): Full read/write permissions for managing index files
* **Collect destination buckets** (where Scanner Collect writes logs): Read/write permissions

See the [Terraform template](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform) for the complete policy structure. If you used [CloudFormation](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/aws-cloudformation) or [manual setup](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/manual-setup-aws-cloudshell), ensure your policy includes all the necessary actions for your use case.

## Troubleshooting Steps

### 1. Re-run Validation

After making changes to your IAM policy or S3 configuration:

1. Go to **Settings > AWS Accounts** in Scanner
2. Click the account with errors
3. Click **Refresh** to trigger a new check

### 2. Check IAM Role Permissions

Verify your Scanner IAM role has the correct inline or managed policies:

1. Navigate to **IAM > Roles** in your AWS Console
2. Search for your Scanner role (e.g., `scnr-IntegrationRole`)
3. Review the attached policies under the "Permissions" tab
4. Ensure all required S3 permissions are included for:
   * The log buckets you want to index
   * The Scanner index bucket
   * Any Collect destination buckets (if using Scanner Collect)

See the [Terraform template](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform) for the complete IAM policy structure as reference.

### 3. Verify KMS Encryption

If your S3 buckets use custom KMS encryption:

1. Ensure your Scanner IAM role has `kms:Decrypt` and `kms:DescribeKey` permissions for the relevant KMS keys
2. See the [Terraform template](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform) for the complete KMS policy structure

### 5. Check EventBridge Configuration

For event-driven indexing:

1. Verify your S3 log bucket has EventBridge notifications enabled (S3 **Properties** > **Event notifications** > **Amazon EventBridge** > **On**)
2. Ensure an EventBridge rule exists in the same region that matches S3 object-created events and forwards them to Scanner's event bus
3. The EventBridge rule (and its IAM role) must be in the same region as your S3 bucket

## Common Issues

### "NoSuchBucket" Error

This error typically appears in both configuration and permission checks. To resolve:

* Verify the bucket name is spelled correctly in Scanner
* Confirm the bucket exists in your AWS account
* Ensure the bucket is in the same account linked to Scanner (not a cross-account setup)
* Check that you have the correct Scanner role ARN in Scanner's settings

### Multiple Buckets with Different Permissions

If you have multiple S3 buckets (log files + index files) with different error patterns:

* Review which bucket each error is associated with (shown in Scanner's UI)
* Ensure your IAM policy grants permissions to all relevant buckets
* Remember: **Index Files Bucket** needs write permissions, **Log Buckets** need read permissions

### Regional Mismatch Issues

* EventBridge rules only receive S3 events from buckets in the same region as the rule
* If you have buckets in multiple regions, create the EventBridge rule (and its IAM role) in each region, or deploy the CloudFormation/Terraform stack in each region
* Verify all resources are in regions where Scanner's infrastructure is deployed

### IAM User Instead of Role

Scanner cannot assume IAM Users. Ensure you create an IAM Role, not an IAM User.

### Missing KMS Permissions

If your S3 buckets use custom KMS encryption, ensure your Scanner IAM role has `kms:Decrypt` and `kms:DescribeKey` permissions for those specific KMS keys. See the [Terraform template](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform) for the complete KMS policy structure.

### Incomplete IAM Policy

When granting S3 permissions in your IAM policy:

* Grant permissions to **both** the bucket ARN (`arn:aws:s3:::bucket-name`) **and** object ARNs (`arn:aws:s3:::bucket-name/*`)
* Bucket-level permissions (bucket ARN) are needed for actions like `ListBucket`, `GetBucketLocation`, and `GetBucketNotification`
* Object-level permissions (object ARN) are needed for actions like `GetObject`, `PutObject`, and `DeleteObject`

### Malformed ARNs

Double-check all resource identifiers:

* Role ARN format should be: `arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME` (not a user ARN)
* Bucket ARN format should be: `arn:aws:s3:::bucket-name`
* Object ARN format should be: `arn:aws:s3:::bucket-name/*`

### Index Files Bucket vs. Log Files Buckets Confusion

* **Scanner Index Files Bucket** = NEW bucket created just for Scanner's index files (Scanner needs write access)
* **Log Files Buckets** = Your EXISTING buckets with raw logs (Scanner needs read-only access)

Make sure you're configuring the correct IAM permissions for each bucket type.

### EventBridge Rule Not in Same Region as Logs

The EventBridge rule (and its IAM role) must be in the same region as your S3 log buckets. Multi-region setups require the rule to be created in each region where you have buckets. See the [Terraform template](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/terraform) or [manual setup](https://docs.scanner.dev/scanner/getting-started/step-1-aws-infrastructure-setup/manual-setup-aws-cloudshell) for guidance on multi-region configurations.

### Multiple Errors From Same Root Cause

You may see multiple errors stemming from the same root cause. For example, if a bucket has been deleted, the bucket presence check will fail, and many other checks on that bucket will also fail or show as "Not checked" because they couldn't proceed. When troubleshooting, focus on resolving the primary issue first (like recreating the bucket or fixing the primary permission), then re-run the validation to clear cascading errors.

## Still Having Issues?

If errors persist after following these steps:

1. Double-check all resource ARNs and bucket names for typos
2. Review AWS CloudTrail logs for access denied errors from Scanner's actions
3. Ensure your AWS credentials/role have not been revoked or rotated
4. Contact Scanner support with the specific error message and affected bucket/resource