# Troubleshooting

This guide helps you diagnose and resolve common issues when configuring and using Storage Connections. Issues are organized by category to help you quickly find relevant solutions.

## Configuration Issues

### Access Denied Errors

Access denied errors typically indicate problems with IAM permissions or trust relationships.

**Symptoms:**

- “Access Denied” when testing storage connection
- Cannot list bucket contents
- Cannot read or write files

**Solutions:**

1. **Verify Trust Relationship**
   - Ensure the trust relationship includes the correct Vendia account IDs from your storage connection configuration
   - Check that the trust policy allows `sts:AssumeRole` action
   - Verify there are no conditional statements in the trust policy that might block access
2. **Check IAM Role Permissions**
   - For read operations: Ensure the IAM role has `s3:GetObject` and `s3:ListBucket` permissions
   - For write operations: Ensure the IAM role has `s3:PutObject` permission in addition to read permissions
   - Verify the resource ARNs in the policy match your actual bucket name and paths
3. **Review Bucket Policies**
   - Check that bucket policies don’t explicitly deny access to Vendia accounts
   - Ensure bucket policies aren’t conflicting with IAM role permissions
   - Verify any bucket policy conditions are being met

**Example Corrected Trust Policy:**

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::VENDIA_ACCOUNT_ID1:root",
          "arn:aws:iam::VENDIA_ACCOUNT_ID2:root"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

### Bucket Not Found Errors

**Symptoms:**

- “Bucket does not exist” error
- “NoSuchBucket” error messages
- Connection test fails with bucket-related errors

**Solutions:**

1. **Verify Bucket Configuration**
   - Confirm the bucket name is spelled correctly (bucket names are case-sensitive)
   - Verify the bucket region matches the region specified in your storage connection configuration
   - Check that the bucket exists and is accessible from the AWS console
2. **Check Regional Settings**
   - Ensure the bucket is in a region supported by Vendia
   - Verify you’re specifying the correct AWS region in the storage connection configuration
   - Consider creating the bucket in a different region if the current one isn’t supported
3. **Validate Bucket Access**
   - Test bucket access from the AWS console with the same IAM role
   - Verify you have the necessary permissions to access the bucket
   - Check if the bucket has been deleted or moved

### Authentication Failed Errors

**Symptoms:**

- “Authentication failed” when creating storage connection
- “Cannot assume role” errors
- “InvalidUserID.NotFound” errors

**Solutions:**

1. **Validate Role ARN**
   - Check that the Role ARN format is correct: `arn:aws:iam::ACCOUNT-ID:role/ROLE-NAME`
   - Verify the role exists in your AWS account
   - Ensure there are no typos in the role ARN
2. **Check Role Assumability**
   - Ensure the role can be assumed by the Vendia account IDs
   - Verify the trust relationship is correctly configured
   - Check for any conditional statements that might prevent role assumption
3. **Review Account Information**
   - Confirm you’re using the correct Vendia account IDs from the storage connection UI
   - Verify the account IDs haven’t changed (though this is rare)
   - Ensure you’re in the correct AWS account

## Operational Issues

### Permission Denied During Operations

**Symptoms:**

- Can create storage connection but cannot read/write files
- “Access Denied” errors during file operations
- Operations work for some paths but not others
- “Unauthorized” errors when using MCP tools

**Solutions:**

1. **Check Both Permission Layers:**
   
   Storage Connections use a two-layer permission system. For an operation to succeed, **both** layers must allow it:
   - **IAM Permissions** (AWS level): Sets the outer boundary
   - **Access Policies** (Vendia level): Further restricts within IAM boundaries
2. **For Read Operations:**
   - **IAM**: Verify the role includes `s3:GetObject` permission for the specific paths
   - **IAM**: Check that `s3:ListBucket` permission includes the correct bucket ARN
   - **Access Policy**: Ensure the file path matches a pattern with `FILE_READ` action
   - Check that there are no bucket policies blocking read access
3. **For Write Operations:**
   - **IAM**: Verify the role includes `s3:PutObject` permission for the target paths
   - **Access Policy**: For new files, ensure `FILE_CREATE` is granted
   - **Access Policy**: For existing files, ensure `FILE_WRITE` is granted (not just `FILE_CREATE`)
   - Check that the specific path where files are being created has both IAM and policy permissions
4. **For Delete Operations:**
   - **IAM**: Verify the role includes `s3:DeleteObject` permission
   - **Access Policy**: Ensure the file path matches a pattern with `FILE_DELETE` action
   - Verify the resource ARNs in your IAM policy include the correct prefixes
5. **Path-Specific Issues:**
   - Review your IAM policy to ensure it covers the specific paths being accessed
   - Check your access policies to ensure glob patterns match the intended files
   - Test pattern matching: `foo/*` (direct children only) vs `foo/**` (all descendants)
   - Verify you’re not being blocked by a more restrictive overlapping policy
6. **Access Policy Troubleshooting:**
   - Review the Access Policy tab in your Storage Connection
   - Check for overlapping or conflicting policies
   - Verify glob patterns match your intended files (test with explicit paths)
   - Ensure you didn’t accidentally create overly restrictive patterns
   - Check if Storage Connections created before access policies have the expected default policy granting all actions

### File Creation Failed Errors

**Symptoms:**

- “File creation failed” errors
- Upload operations timeout or fail
- Content is created but appears corrupted
- Cannot overwrite existing files

**Solutions:**

1. **Check Bucket Capacity and Policies**
   - Confirm the bucket has sufficient space for new files
   - Verify there are no restrictive bucket policies preventing file creation
   - Check if versioning settings are causing issues
2. **Validate File Paths and Names**
   - Ensure the file path and naming conventions are valid for S3
   - Check that file names don’t contain invalid characters
   - Verify the folder structure exists or can be created
3. **Content Type and Format Issues**
   - Check that the content type is appropriate for the file being created
   - Verify file encoding is correct (especially for text files)
   - Ensure binary files are being handled properly
4. **File Overwrite Issues**

If you’re trying to overwrite an existing file and getting errors:

- **Check Access Policy**: Verify the policy includes `FILE_WRITE` (not just `FILE_CREATE`)
   - **`FILE_CREATE` vs `FILE_WRITE`**: Remember that `FILE_CREATE` only allows creating new files, not overwriting existing ones
   - **IAM Permissions**: Ensure your IAM role has `s3:PutObject` permission for the path
   - **Solution**: Either use `FILE_WRITE` in your access policy, or delete the existing file first (requires `FILE_DELETE`)

## Connection Management Issues

### Storage Connection Not Appearing

**Symptoms:**

- Storage connection doesn’t appear in the dashboard after creation
- Connection status shows as failed or pending
- Cannot see connected buckets

**Solutions:**

1. **Check Connection Status**
   - Refresh the storage connections page
   - Verify the connection was successfully created (check for error messages)
   - Look for any pending validations or approvals
2. **Validate Configuration**
   - Ensure all required fields were filled correctly
   - Verify the Role ARN is accessible and formatted correctly
   - Check that the bucket region is supported
3. **Account and Permission Issues**
   - Confirm you have the necessary permissions to view storage connections
   - Verify you’re in the correct Vendia workspace/project
   - Check if there are any account-level restrictions

### Cannot Delete Storage Connection

**Symptoms:**

- Delete button is disabled or missing
- “Cannot delete” error messages
- Connection appears to delete but reappears

**Solutions:**

1. **Check Dependencies**
   - Verify no active AI applications are using the storage connection
   - Ensure no ongoing operations are using the connection
   - Look for any dependent configurations that need to be removed first
2. **Permission Issues**
   - Confirm you have the necessary permissions to delete storage connections
   - Check if you’re an admin or have the required role in your Vendia account
   - Verify there are no organizational policies preventing deletion

## Performance Issues

### Slow File Operations

**Symptoms:**

- Long delays when reading or writing files
- Timeouts during large file operations
- Inconsistent response times

**Solutions:**

1. **Regional Optimization**
   - Consider moving your bucket to a region closer to the Vendia service
   - Check if cross-region data transfer is causing delays
   - Verify you’re using the most appropriate AWS region
2. **File Size and Type Considerations**
   - For large files, consider breaking them into smaller pieces
   - Use appropriate file formats that are efficient for your use case
   - Be aware of size limitations for certain file types in chat-based agents
3. **S3 Performance Optimization**
   - Implement S3 transfer acceleration if needed
   - Consider using multipart uploads for large files (handled automatically by AWS)
   - Review your S3 request patterns for optimization opportunities

## Advanced Troubleshooting

### CloudTrail Investigation

For complex issues, use AWS CloudTrail to investigate:

1. **Enable CloudTrail** for your S3 bucket if not already enabled
2. **Search for events** related to your storage operations
3. **Look for patterns** in failed requests or access attempts
4. **Check for any policy evaluation details** in the logs

### IAM Policy Testing

Use AWS IAM Policy Simulator to test your policies:

1. **Access the IAM Policy Simulator** in the AWS console
2. **Select your IAM role** and the policies you want to test
3. **Simulate S3 operations** (GetObject, ListBucket, PutObject) against your bucket
4. **Review the results** to understand policy evaluation

### Network and Connectivity

For connectivity issues:

1. **Check AWS service status** for your region
2. **Verify network connectivity** from your location
3. **Review any firewall or proxy settings** that might affect connections
4. **Test with different networks** if possible

## Getting Additional Help

### Self-Service Resources

- **[Best Practices Guide](https://docs.vendia.com/platform/vendia-mcp-server/storage-connections/best-practices)**: Follow recommended practices to prevent issues
- **[Creating Storage Connections](https://docs.vendia.com/platform/vendia-mcp-server/storage-connections/creating-storage-connections)**: Review setup steps if configuration issues persist
- **[MCP Server FAQ](https://docs.vendia.com/platform/vendia-mcp-server/faq)**: Check common questions and answers

### Free Tier Support

- Review the [MCP Free Tier FAQ](https://docs.vendia.com/platform/free-tier-faq) for Free Tier-specific questions
- Submit questions via our [contact form](https://www.vendia.com/contact-us/) (online support only)

### Enterprise Tier Support

- Contact [Vendia Support](mailto:support@vendia.com) for technical assistance
- Include relevant error messages, configuration details, and steps you’ve already tried
- Provide CloudTrail logs or other diagnostic information when possible

## Quick Reference

### Common Error Codes

| Error Code       | Common Cause                        | Quick Fix                                   |
| ----------------- | ------------------------------------- | ------------------------------------------ |
| AccessDenied      | IAM permissions issue                | Check role permissions and trust relationship |
| NoSuchBucket      | Bucket name or region mismatch       | Verify bucket name and region             |
| InvalidRole       | Role ARN issue                       | Check role ARN format and existence       |
| AuthenticationFailed | Trust relationship issue          | Verify Vendia account IDs in trust policy  |

### Diagnostic Checklist

Before contacting support, verify the following:

- Role ARN is correctly formatted and exists
- Trust relationship includes correct Vendia account IDs
- IAM policy includes necessary S3 permissions
- Bucket name and region are correct
- No conflicting bucket policies
- File paths and names are valid for S3
- Connection appears in storage connections dashboard