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 or FILE_ALL 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, FILE_WRITE, or FILE_ALL is granted
   • Access Policy: For existing files, ensure FILE_WRITE or FILE_ALL 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 or FILE_ALL 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 FILE_ALL policy

See Access Policies for detailed configuration guidance.

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 or FILE_ALL (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/FILE_ALL in your access policy, or delete the existing file first (requires FILE_DELETE)

   See Access Policies - FILE_WRITE vs FILE_CREATE for details.

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: Follow recommended practices to prevent issues
• Creating Storage Connections: Review setup steps if configuration issues persist
• MCP Server FAQ: Check common questions and answers

Free Tier Support

• Review the MCP Free Tier FAQ for Free Tier-specific questions
• Submit questions via our contact form (online support only)

Enterprise Tier Support

• Contact Vendia Support 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