OX
OnglX

Troubleshooting

Common issues and solutions

Support

Common Issues

AWS Authentication Errors

Problem:

Getting "Unable to locate credentials" or "Access Denied" errors

Terminal - OnglX Deploy
Error: Unable to locate credentials. You can configure 
credentials by running "aws configure"

Solutions:

  • • Verify AWS CLI is installed and configured: aws sts get-caller-identity
  • • Check your AWS credentials are valid and not expired
  • • Ensure your user/role has the required permissions
  • • Try re-running: aws configure
Bedrock Access Denied

Problem:

Cannot access Bedrock models or getting access denied errors

Terminal - OnglX Deploy
Error: You don't have access to the model with the specified 
model ID. Make sure to request access to the model

Solutions:

  • • Go to AWS Bedrock console and request model access
  • • Verify Bedrock is available in your region: aws bedrock list-foundation-models --region us-east-1
  • • Check your IAM permissions include Bedrock access
  • • Some models require additional approval from AWS
Deployment Failures

Problem:

Deployment fails with resource creation errors

Terminal - OnglX Deploy
Error: Failed to create resource: Resource limit exceeded 
or service quota reached

Solutions:

  • • Check AWS service quotas in your account
  • • Try a different region with more capacity
  • • Clean up unused resources to free up quota
  • • Request quota increases if needed
  • • Use rollback to clean up partial deployments: onglx-deploy destroy
API Connection Issues

Problem:

Cannot connect to deployed API endpoints or getting timeout errors

Terminal - OnglX Deploy
Error: Connection timeout when calling API endpoint
or 502 Bad Gateway errors

Solutions:

  • • Check API status: onglx-deploy status
  • • View API logs: onglx-deploy logs api
  • • Verify API gateway and Lambda function are running
  • • Check security groups and networking configuration
  • • Try re-deploying if resources are corrupted

Debugging Tools

Built-in Commands

Check deployment status:

Terminal - OnglX Deploy
$ onglx-deploy status
Deployment Status for aws in us-east-1
=====================================
Components:
  [✓] api/openai: Healthy  
  [✗] ui/openwebui: Unhealthy

View detailed logs:

Terminal - OnglX Deploy
$ onglx-deploy logs --follow
[api] 2024-01-01T12:00:00Z ERROR: Model access denied
[ui]  2024-01-01T12:00:01Z INFO: Starting service...
AWS Console

Check AWS resources:

  • • CloudFormation stacks and events
  • • Lambda function logs in CloudWatch
  • • API Gateway execution logs
  • • ECS service and task status
  • • Bedrock model access and usage

Performance Issues

Slow API Response Times

If your API responses are slower than expected:

  • • Bedrock models have cold start times - first requests may be slower
  • • Check CloudWatch metrics for Lambda duration and Bedrock latency
  • • Consider using provisioned concurrency for Lambda functions
  • • Monitor Bedrock throttling limits and request patterns

UI Loading Slowly

If your UI component is slow to load:

  • • ECS tasks have startup time - first requests may be slower
  • • Check ECS service auto-scaling configuration
  • • Monitor EFS mount performance
  • • Consider increasing task CPU/memory allocation

Getting Help

Still need help?

  • • Check the AWS Setup Guide for configuration issues
  • • Review CLI command documentation for usage examples
  • • Share debug output when reporting issues: onglx-deploy status --verbose
  • • Include your deploy.yml configuration (remove sensitive data)

💡 Pro Tips

  • • Always run onglx-deploy plan before deploying to catch issues early
  • • Use --auto-approve flag cautiously - review changes first
  • • Keep your AWS CLI and OnglX Deploy CLI updated to the latest versions
  • • Monitor your AWS costs and set up billing alerts