Troubleshooting

Solutions to common issues when running StackSage audits.

Authentication Issues

Error: "User is not authorized to perform: sts:AssumeRoleWithWebIdentity"

Cause: The OIDC provider is not configured or the trust policy is incorrect.

Solution:

1. Verify the OIDC provider exists in IAM Console → Identity providers
2. Check the trust policy references the correct GitHub org/repo
3. Ensure the audience is set to sts.amazonaws.com

# Verify trust policy
aws iam get-role --role-name StackSageAuditor --query 'Role.AssumeRolePolicyDocument'

Error: "Access Denied" on specific API calls

Cause: Missing IAM permissions for specific AWS services.

Solution: Compare your policy against the reference policy and add missing permissions.

Detector Issues

Why didn't a detector find my idle resource?

Detectors use CloudWatch metrics and configurable thresholds. Possible reasons:

• Resource too new: Most detectors skip resources <7 days old
• Metrics not available: CloudWatch metrics may lag or be incomplete
• Threshold not met: Resource may be slightly above idle threshold
• Excluded by config: Check your stacksage.yml exclusions

Too many false positives

Solution: Adjust thresholds in stacksage.yml:

thresholds:
  ebs:
    unattached_days: 14  # More conservative
  nat_gateway:
    idle_threshold_gb_per_day: 0.1  # Stricter threshold
  
reporting:
  min_savings_usd: 25  # Filter out small findings

Detector disabled but still showing findings

Cause: Configuration file not loaded or typo in detector name.

Solution:

1. Verify stacksage.yml is in repository root
2. Check detector ID matches exactly (case-sensitive)
3. Look for "Configuration applied" in provenance section of report

Report Issues

No report artifact generated

Cause: Workflow failed before upload step.

Solution:

1. Check GitHub Actions logs for errors
2. Verify AWS credentials are valid
3. Ensure output directory matches upload artifact path

Report shows "No findings"

This may be legitimate if your AWS environment is well-optimized! However, verify:

• Correct region: Ensure you're scanning the right AWS region
• Permissions: Check for "Access Denied" in logs
• Filters too strict: Review reporting.min_savings_usd and severity_filter

Configuration Issues

Configuration file not being loaded

Symptoms: No "Configuration applied" in provenance section.

Solution:

1. Confirm file is named exactly stacksage.yml (not .yaml)
2. Place in repository root (same level as .github/)
3. Check YAML syntax with a validator

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('stacksage.yml'))"

Tag-based exclusion not working

Cause: Resource doesn't have the specified tag, or tag value doesn't match.

Solution:

• Verify tag exists on resource in AWS Console
• Tag matching is case-sensitive (key and value)
• Check report's "Resource Details" section to see actual tags

Performance Issues

Workflow takes too long (>15 minutes)

Causes: Large AWS environment, many regions, or API throttling.

Solutions:

• Limit regions: Only scan regions with resources
• Split workflows: Create separate workflows per account/region
• Adjust concurrency: CloudWatch queries run with budget limits

# Limit to specific regions
exclusions:
  regions:
    - us-west-1
    - eu-central-1
    - ap-northeast-1  # Exclude unused regions

CloudWatch API throttling errors

StackSage automatically handles throttling with exponential backoff. If errors persist:

• Consider requesting a CloudWatch API limit increase
• Run audits less frequently (e.g., weekly instead of daily)
• The budget system will skip metrics if quota is exhausted

Cost Estimation Issues

Cost estimates seem incorrect

Cost estimates are approximations based on:

• AWS public pricing API (updated quarterly)
• Resource configurations at scan time
• Standard on-demand pricing (no RIs or SPs)

For precise costs, use AWS Cost Explorer or your billing console.

Getting Help

Related Topics

• Quick Start Guide
• IAM Policy Setup
• Configuration Guide
• All Detectors