Troubleshooting Guide

Common issues and solutions for OpsCurb.

Connection Issues

❌ "Failed to assume IAM role"

Symptoms: Scan fails with "AssumeRole failed" error

Causes:

IAM role doesn't exist
External ID mismatch
Trust policy incorrect
Role ARN incorrect

Solutions:

1. Verify IAM role exists:

aws iam get-role --role-name OpsCurbRole

2. Check External ID:

Go to OpsCurb dashboard → Settings → AWS Accounts
Copy the External ID
Verify it matches the trust policy:

aws iam get-role --role-name OpsCurbRole --query 'Role.AssumeRolePolicyDocument'

3. Verify trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::123456789012:root"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "YOUR_EXTERNAL_ID"
      }
    }
  }]
}

4. Update role ARN:

Format: arn:aws:iam::YOUR_ACCOUNT_ID:role/OpsCurbRole
Verify account ID is correct

❌ "Access Denied" errors

Symptoms: Scan partially completes, some scanners fail

Cause: Missing IAM permissions

Solution:

1. Check IAM policy:

aws iam list-attached-role-policies --role-name OpsCurbRole

2. Verify permissions: Compare with our required permissions in terraform/main.tf

3. Update policy:

cd terraform/
terraform apply

4. Test specific permission:

# Test EC2 describe permission
aws ec2 describe-volumes --max-results 1

# Test RDS describe permission
aws rds describe-db-instances --max-records 1

❌ "Connection timeout"

Symptoms: Scan hangs or times out

Causes:

AWS API throttling
Network issues
Large infrastructure

Solutions:

1. Check AWS service health:

Visit: https://status.aws.amazon.com/
Check regions you're scanning

2. Reduce scan scope:

Scan fewer regions
Exclude specific scanners
Increase timeout in settings

3. Retry the scan:

Wait 5-10 minutes
Run scan again

Scan Issues

❌ "No findings detected"

Symptoms: Scan completes but shows 0 findings

Possible reasons:

1. Your infrastructure is optimized! 🎉

This is good news!
Review scan details to confirm all scanners ran

2. Filters are too restrictive:

Check Settings → Preferences → Cost Thresholds
Lower minimum cost thresholds
Check region filters

3. Permissions issue:

Some scanners may have failed silently
Check scan logs for errors
Verify all IAM permissions

4. Scan still running:

Wait for scan to complete (typically 2-5 minutes)
Refresh the page

❌ "Scan failed"

Symptoms: Scan status shows "failed"

Solutions:

1. Check error message:

Click on the failed scan
Read the error details
Follow specific error guidance

2. Common errors:

Error	Solution
"AssumeRole failed"	See "Failed to assume IAM role" above
"Access Denied"	See "Access Denied" above
"Timeout"	Retry scan, reduce scope
"Invalid credentials"	Update AWS credentials
"Region not enabled"	Enable region in AWS or exclude from scan

3. Retry scan:

Click "Retry Scan"
Or run a new scan

❌ Scan takes too long

Symptoms: Scan runs for > 10 minutes

Causes:

Large infrastructure (1000+ resources)
Many regions enabled
AWS API throttling

Solutions:

1. Optimize scan scope:

Settings → Scan Configuration
- Reduce number of regions
- Disable unused scanners
- Increase scan timeout

2. Schedule scans during off-peak:

Avoid peak AWS usage times
Schedule for nights/weekends

3. Contact support (Enterprise):

We can optimize scan performance
Dedicated scanning infrastructure available

Dashboard Issues

❌ Dashboard not loading

Symptoms: Blank page or loading spinner

Solutions:

1. Clear browser cache:

Chrome: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
Firefox: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
Safari: Cmd+Option+E (Mac)

2. Try incognito/private mode:

Chrome: Ctrl+Shift+N
Firefox: Ctrl+Shift+P
Safari: Cmd+Shift+N

3. Check browser console:

Press F12
Look for errors in Console tab
Send errors to support@opscurb.com

4. Try different browser:

We support Chrome, Firefox, Safari, Edge
Update to latest browser version

❌ "Session expired" errors

Symptoms: Logged out frequently

Solutions:

1. Enable cookies:

Check browser settings
Allow cookies for opscurb.com

2. Disable browser extensions:

Ad blockers may interfere
Privacy extensions may block cookies

3. Check system time:

Ensure system clock is accurate
JWT tokens are time-sensitive

Notification Issues

❌ Not receiving Slack notifications

Symptoms: Scans complete but no Slack messages

Solutions:

1. Verify integration:

Settings → Integrations → Slack
- Check "Connected" status
- Test integration

2. Check Slack webhook:

Webhook URL should start with https://hooks.slack.com/
Verify webhook is active in Slack settings

3. Check notification settings:

Settings → Notifications
- Enable "Slack Notifications"
- Select notification triggers

4. Test notification:

Click "Send Test Notification"
Check Slack channel

❌ Not receiving email notifications

Symptoms: No email alerts

Solutions:

1. Check spam folder:

Look for emails from noreply@opscurb.com
Add to safe senders list

2. Verify email address:

Settings → Profile
- Check email address is correct
- Verify email address

3. Check notification settings:

Settings → Notifications
- Enable "Email Notifications"
- Select notification triggers

4. Email provider issues:

Some providers block automated emails
Try different email address
Contact support for whitelisting

API Issues

❌ "401 Unauthorized"

Symptoms: API requests fail with 401 error

Solutions:

1. Check API token:

# Test token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.opscurb.com/api/health

2. Regenerate token:

Settings → API Keys → Revoke → Generate New

3. Check token format:

Should be: Authorization: Bearer YOUR_TOKEN
Not: Authorization: YOUR_TOKEN

❌ "429 Too Many Requests"

Symptoms: API requests fail with 429 error

Cause: Rate limit exceeded

Solutions:

1. Check rate limits:

Free: 1,000 req/hour
Starter: 5,000 req/hour
Pro: 10,000 req/hour

2. Implement backoff:

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait_time = int(response.headers.get('Retry-After', 60))
            time.sleep(wait_time)
            continue
        return response
    raise Exception("Max retries exceeded")

3. Upgrade plan:

Higher plans have higher rate limits

Billing Issues

❌ Payment failed

Symptoms: "Payment failed" notification

Solutions:

1. Update payment method:

Settings → Billing → Update Payment Method

2. Check card details:

Expiration date
Billing address
CVV code

3. Contact bank:

Some banks block international payments
Whitelist Stripe (our payment processor)

4. Try different card:

Use different credit/debit card

❌ Can't cancel subscription

Symptoms: Cancel button not working

Solutions:

1. Clear outstanding invoices:

Pay any unpaid invoices first
Then cancel subscription

2. Contact support:

Email: billing@opscurb.com
We'll cancel manually

Performance Issues

❌ Dashboard is slow

Solutions:

1. Reduce data range:

View fewer scans
Filter by date range
Limit findings displayed

2. Clear browser cache:

See "Dashboard not loading" above

3. Check internet connection:

Run speed test
Try different network

4. Upgrade browser:

Use latest browser version
Enable hardware acceleration

Data Issues

❌ Cost estimates seem wrong

Symptoms: Estimated costs don't match AWS bill

Explanation:

Our cost estimates are based on:

AWS public pricing (updated monthly)
Resource metadata (size, type, region)
Standard pricing (not your specific discounts)

Accuracy: Typically ±10%

Reasons for differences:

You have AWS discounts (Reserved Instances, Savings Plans)
You're in a different pricing tier
AWS pricing changed recently
Resource metadata is incomplete

Solution:

Use estimates as relative comparison
Verify actual costs in AWS Cost Explorer
Contact support for custom pricing

❌ Missing resources

Symptoms: Resources exist in AWS but not in scan results

Causes:

Resource in unsupported region
Resource type not scanned yet
Permissions issue
Resource created after scan

Solutions:

1. Check scan regions:

Settings → Scan Configuration → Regions

2. Check scanner types:

We scan 14 resource types
See SCANNERS_DOCUMENTATION.md

3. Run new scan:

Resources created after scan won't appear
Run new scan to detect new resources

Still Having Issues?

Contact Support

Email: support@opscurb.com

Include:

Description of the issue
Steps to reproduce
Screenshots (if applicable)
Error messages
Your account ID
Browser/OS information

Response times:

Free: 48 hours
Starter: 24 hours
Pro: 4 hours
Enterprise: 1 hour

Check Status Page

URL: status.opscurb.com

Check for:

Service outages
Scheduled maintenance
Known issues

Community Forum

URL: community.opscurb.com

Search for similar issues
Ask the community
Share solutions

Last Updated: 2026-02-24
Version: 1.0