|
| 1 | +# Troubleshooting Guide |
| 2 | + |
| 3 | +This guide helps you troubleshoot common issues you might encounter when using the Bedrock Access Gateway. |
| 4 | + |
| 5 | +## Common Issues |
| 6 | + |
| 7 | +### 1. Parameter Store Access Error |
| 8 | + |
| 9 | +To see errors, first you need to access the CloudWatch Logs of the Lambda/Fargate instance. |
| 10 | + |
| 11 | +1. Go to the [CloudWatch Console](https://console.aws.amazon.com/cloudwatch/home?#logsV2:log-groups/) |
| 12 | +2. Search for `/aws/lambda/BedrockProxyAPI` |
| 13 | +3. Click on the `Log Stream` to see the error details |
| 14 | + |
| 15 | +```python |
| 16 | +botocore.exceptions.ClientError: An error occurred (ParameterNotFound) when calling the GetParameter operation: Parameter /BedrockProxyAPIKey not found. |
| 17 | +``` |
| 18 | + |
| 19 | +This error occurs when the Lambda function cannot access the API key parameter in Parameter Store. |
| 20 | + |
| 21 | +**Possible solutions:** |
| 22 | +- Verify that you created the parameter in Parameter Store with the correct name |
| 23 | +- Check that the parameter name in the CloudFormation stack matches the one in Parameter Store |
| 24 | +- Ensure the Lambda function's IAM role has permission to access Parameter Store |
| 25 | +- If you didn't set up an API key, leave the `ApiKeyParam` field blank during deployment |
| 26 | + |
| 27 | +### 2. Model Access Issues |
| 28 | + |
| 29 | +If you receive an error about model access: |
| 30 | + |
| 31 | +``` |
| 32 | +{"error": {"message": "User: arn:aws:iam::XXXX:role/XXX is not authorized to perform: bedrock:InvokeModel on resource: arn:aws:bedrock:REGION::foundation-model/XXX", "type": "auth_error", "code": 401}} |
| 33 | +``` |
| 34 | + |
| 35 | +**Possible solutions:** |
| 36 | +- Ensure you have requested access to the model in Amazon Bedrock |
| 37 | +- Verify the Lambda/Fargate role has the necessary permissions to invoke Bedrock models |
| 38 | +- Check that you're using the correct model ID |
| 39 | +- Verify the model is available in your chosen region |
| 40 | + |
| 41 | +### 3. API Key Authentication Failures |
| 42 | + |
| 43 | +If you receive a 401 Unauthorized error: |
| 44 | + |
| 45 | +``` |
| 46 | +{"detail": "Could not validate credentials"} |
| 47 | +``` |
| 48 | + |
| 49 | +**Possible solutions:** |
| 50 | +- Verify you're using the correct API key in your requests |
| 51 | +- Check that the `Authorization` header is properly formatted (`Bearer YOUR-API-KEY`) |
| 52 | +- If using environment variables, ensure `OPENAI_API_KEY` is set correctly |
| 53 | + |
| 54 | +### 4. Cross-Region Access Issues |
| 55 | + |
| 56 | +If you're trying to access models in a different region: |
| 57 | + |
| 58 | +``` |
| 59 | +{"error": {"message": "Region 'us-east-1' is not enabled for your account", "type": "invalid_request_error", "code": 400}} |
| 60 | +``` |
| 61 | + |
| 62 | +**Possible solutions:** |
| 63 | +- Ensure the target region is enabled for your AWS account |
| 64 | +- Verify the model you're trying to access is available in that region |
| 65 | +- Check that your IAM roles have the necessary cross-region permissions |
| 66 | + |
| 67 | +### 5. Rate Limiting and Quotas |
| 68 | + |
| 69 | +If you're experiencing throttling or quota issues: |
| 70 | + |
| 71 | +``` |
| 72 | +{"error": {"message": "Rate limit exceeded", "type": "rate_limit_error", "code": 429}} |
| 73 | +``` |
| 74 | + |
| 75 | +**Possible solutions:** |
| 76 | +- Check your Bedrock service quotas in the AWS Console |
| 77 | +- Consider implementing retry logic in your application |
| 78 | +- Request a quota increase if needed |
| 79 | + |
| 80 | +## Getting Help |
| 81 | + |
| 82 | +If you're still experiencing issues: |
| 83 | + |
| 84 | +1. Check the CloudWatch Logs for detailed error messages |
| 85 | +2. Verify your AWS credentials and permissions |
| 86 | +3. Review the [Usage Guide](./Usage.md) for correct API usage |
| 87 | +4. Open a [GitHub issue](https://github.com/aws-samples/bedrock-access-gateway/issues/new?template=bug_report.md) with: |
| 88 | + - Detailed error message |
| 89 | + - Steps to reproduce |
| 90 | + - Your deployment configuration (region, model, etc.) |
| 91 | + - Any relevant CloudWatch logs |
| 92 | + |
| 93 | +## Additional Resources |
| 94 | + |
| 95 | +- [Amazon Bedrock Documentation](https://docs.aws.amazon.com/bedrock/) |
| 96 | +- [AWS IAM Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/) |
| 97 | +- [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) |
0 commit comments