Troubleshooting Guide - Amazon Bio Discovery

Login and Access Issues

Cannot Sign In

Check Credentials: Verify AWS account or SSO credentials
Organization ID: Ensure correct organization ID is entered
Browser Issues: Clear cache, try incognito mode, or different browser
Network: Check VPN or firewall settings

Permission Denied Errors

Contact Admin: Request access from organization administrator
Role Assignment: Verify appropriate role has been assigned
Resource Access: Check project or recipe sharing settings

Quick Fix

Try signing out completely and signing back in. This refreshes your session and permissions.

Protein Structure Search Access

Protein structure search requires the AWS managed policy AmazonBioDiscoveryInAppFullAccess on your Amazon Bio Discovery application role. An IT administrator with iam:AttachRolePolicy permission must complete this update.

If you are not an IT administrator

Send these instructions to the team that manages AWS permissions for your organization. Attaching the policy is additive, does not remove existing permissions, and restores access without changing your data.

Choose one of the following options. Both options attach the same policy. Complete either the AWS Management Console steps or the AWS CLI steps; you do not need to complete both.

Option 1 - AWS Management Console (recommended)

Open the Amazon Bio Discovery Console at https://console.aws.amazon.com/biodiscovery/home.
Locate your application in the My Amazon Bio Discovery applications section and choose the service role link, which opens the role in the IAM console.
Alternatively, open the IAM console, choose Roles, and search for your role. Unless you customized it during application creation, the role name starts with AmazonBioDiscoveryAccessRole.
On the role's Permissions tab, choose Add permissions, and then choose Attach policies.
Search for AmazonBioDiscoveryInAppFullAccess, select the check box next to the policy, and then choose Add permissions.
Confirm that AmazonBioDiscoveryInAppFullAccess now appears in the list of attached policies for the role.
Return to the application portal and retry the action that failed.

Option 2 - AWS CLI

If you manage IAM with the AWS CLI, run the following commands from a session with IAM administrative credentials for your account.

Important

The credentials you use must allow iam:ListRoles and iam:AttachRolePolicy. If your account uses AWS Organizations service control policies or permissions boundaries that restrict IAM actions, contact your AWS administrator to perform this step.

Identify the service role used by your application. The role name is shown on your application's details page in the Amazon Bio Discovery Console, as described in Option 1, step 2. You can also list candidate roles with the following command, which returns roles whose name begins with the default prefix:
```
aws iam list-roles \
  --query "Roles[?starts_with(RoleName, 'AmazonBioDiscoveryAccessRole')].RoleName"
```
Important

If you renamed the role when you created the application, this command does not return it. Use the Amazon Bio Discovery Console to find the role name instead.

Attach the AWS managed policy, replacing YOUR_ROLE_NAME with the role name from the previous step:

aws iam attach-role-policy \
  --role-name YOUR_ROLE_NAME \
  --policy-arn arn:aws:iam::aws:policy/AmazonBioDiscoveryInAppFullAccess

Verify that the policy is attached. The following command returns the policy name and ARN if the change succeeded, and an empty list if it did not:
```
aws iam list-attached-role-policies \
  --role-name YOUR_ROLE_NAME \
  --query "AttachedPolicies[?PolicyName=='AmazonBioDiscoveryInAppFullAccess']"
```
Return to the application portal and retry the action that failed.

Important

After attaching the policy, sign out of your Amazon Bio Discovery application portal and sign back in (or refresh the page) to pick up the updated permissions, then retry the action. IAM permission changes typically take less than 1 minute to propagate. If the action still fails after you attach the policy, wait 1–2 minutes and try again.

File Upload Problems

Upload Failures

File Size: Ensure files are under 100MB limit
File Format: Verify supported formats (PDB, FASTA, CSV)
Network: Check internet connection stability
Browser: Try different browser or disable extensions

File Validation Errors

PDB Files: Check structure integrity and chain IDs
FASTA Files: Verify sequence format and headers
Character Encoding: Ensure UTF-8 encoding
File Corruption: Re-download and re-upload original file

        Common PDB Issues: - Missing chain identifiers (H, L, T) - Non-standard residue names - Incomplete coordinate
        data - Multiple models without proper headers
      

Experiment Issues

Experiment Fails to Start

Input Validation: Check all required files are uploaded
Parameter Errors: Verify all required parameters are set
Cost Limits: Ensure sufficient credits or budget
Resource Availability: Check system capacity and queues

Experiment Fails During Execution

Input Quality: Review file validation messages
Parameter Values: Check for out-of-range or conflicting settings
Resource Limits: Reduce complexity or dataset size
System Issues: Contact support if persistent failures occur

Poor Quality Results

Input Data: Verify structure quality and completeness
Parameters: Review and adjust key settings
Recipe Selection: Ensure appropriate workflow for objectives
Validation: Compare with known positive controls

Performance Issues

Slow Loading Times

Browser Cache: Clear browser cache and cookies
Network Speed: Check internet connection bandwidth
Large Files: Consider file size optimization
Browser Resources: Close unnecessary tabs and applications

Experiment Takes Too Long

Complexity: Reduce number of designs or parameters
Queue Position: Check system load and wait times
Resource Allocation: Consider upgrading compute tier
Optimization: Use more efficient algorithms or recipes

Performance Tips

Start with smaller experiments to test parameters
Use batch processing for multiple similar experiments
Monitor resource usage patterns
Schedule large experiments during off-peak hours

Results and Analysis Problems

Missing or Incomplete Results

Experiment Status: Verify experiment completed successfully
Output Generation: Check if all modules produced results
File Permissions: Ensure access to result files
Browser Refresh: Reload page to update result display

Visualization Issues

Browser Compatibility: Use supported browsers (Chrome, Firefox, Safari)
WebGL Support: Enable hardware acceleration for 3D visualizations
Data Size: Large datasets may require filtering or sampling
Plugin Issues: Disable browser extensions that might interfere

Download Problems

File Size: Large files may require multiple attempts
Format Selection: Choose appropriate format for your needs
Browser Settings: Check download location and permissions
Network Stability: Ensure stable connection for large downloads

Wet Lab Integration Issues

Cannot Submit to Wet Lab

Selection Required: Ensure candidates are selected
Partner Availability: Check wet lab partner capacity
Assay Configuration: Verify all required assays are selected
Terms Acceptance: Confirm terms and conditions are accepted

Order Status Issues

Status Updates: Allow time for partner processing
Communication: Check for messages from wet lab partner
Contact Information: Verify contact details are current
Order Tracking: Use provided tracking information

Collaboration Problems

Cannot Share Projects

Permissions: Verify you have owner or admin rights
User Existence: Ensure target users exist in organization
Role Limits: Check organization sharing policies
Sync Delays: Allow time for permission propagation

Team Members Cannot Access

Invitation Status: Verify invitations were sent and accepted
Role Assignment: Check assigned permission levels
Organization Membership: Ensure users are in correct organization
Cache Issues: Have users sign out and back in

Error Messages

Common Error Codes

403 Forbidden: Permission denied - contact administrator
413 Payload Too Large: File size exceeds limits
422 Unprocessable Entity: Invalid input data format
429 Too Many Requests: Rate limit exceeded - wait and retry
500 Internal Server Error: System issue - contact support

Validation Messages

"Invalid PDB format": Check file structure and chain IDs
"Missing required parameters": Complete all mandatory fields
"Insufficient credits": Add credits or reduce experiment scope
"File not found": Re-upload missing files

Getting Help

Self-Service Resources

Documentation: Check user guides and tutorials
FAQ: Review frequently asked questions
Community: Search discussion forums
Status Page: Check system status and maintenance

Contacting Support

When contacting support, please include:

Detailed description of the issue
Steps to reproduce the problem
Error messages or screenshots
Browser and operating system information
Experiment or project IDs if relevant

Prevention Tips

Avoiding Common Issues

Validate input files before uploading
Start with small test experiments
Keep browsers and systems updated
Regularly backup important data
Monitor resource usage and limits

Best Practices for Stability

Use recommended file formats and sizes
Follow naming conventions consistently
Document experiment parameters and rationale
Test workflows before large-scale execution
Maintain organized project structures