Skip to main content

CloudWise Troubleshooting Guide

This guide helps you resolve common issues when setting up and using CloudWise with your AWS account.

Common Setup Issues​

1. AWS Account Connection Problems​

Issue: "Unable to connect to AWS account"​

Symptoms:

  • Connection fails during setup
  • Error message: "Access denied" or "Invalid credentials"

Solutions:

  1. Check IAM Role Permissions

    # Verify your IAM role has the correct permissions
    aws iam get-role-policy --role-name CloudWise-Role --policy-name CloudWise-Policy

  2. Validate External ID

    • Ensure the external ID in CloudWise matches your IAM role trust policy
    • External IDs are case-sensitive

  3. Verify Role ARN

    • Double-check the role ARN format: arn:aws:iam::YOUR-ACCOUNT-ID:role/CloudWise-Role
    • Ensure there are no extra spaces or characters

Issue: "Role assumption failed"​

Symptoms:

  • Setup completes but data doesn't load
  • Error in logs: "AssumeRole operation failed"

Solutions:

  1. Trust Policy Configuration

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::CLOUDWISE-ACCOUNT-ID:root"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "StringEquals": {
                        "sts:ExternalId": "your-external-id"
                    }
                }
            }
        ]
    }

  2. Check Account ID

    • Verify you're using the correct CloudWise account ID
    • Contact support if unsure about the account ID

2. Missing Cost Data​

Issue: "No cost data available"​

Symptoms:

  • Dashboard shows empty or incomplete data
  • Message: "Waiting for data to sync..."

Solutions:

  1. Wait for Initial Sync

    • First sync can take 24-48 hours
    • Historical data (up to 12 months) is processed during this time

  2. Check Cost Explorer

    # Verify Cost Explorer is enabled
    aws ce get-cost-and-usage --time-period Start=2024-01-01,End=2024-01-31 --granularity MONTHLY --metrics BlendedCost

  3. Billing Permissions

    • Ensure IAM role has aws-portal:ViewBilling permission
    • Check that Cost Explorer API access is enabled

Issue: "Partial cost data missing"​

Symptoms:

  • Some services or regions show no data
  • Inconsistent cost information

Solutions:

  1. Service-Specific Permissions

    • Add specific service permissions if needed
    • Some services require additional IAM permissions

  2. Regional Data Issues

    • Ensure CloudWise role has global permissions
    • Check if specific regions are restricted in your AWS account
    • Opt-in regions (e.g. Bahrain me-south-1, Cape Town af-south-1, Hong Kong ap-east-1) must be explicitly enabled in your AWS account before CloudWise can scan them. If cost data references an opt-in region you haven't enabled, the scan for that region is skipped with a warning (region {region} is not enabled on this account (opt-in region) — scan skipped; findings from this region are MISSING, not zero) rather than scanned — enable the region in the AWS Console (Account → AWS Regions) to get coverage there.

Data Synchronization Issues​

3. Slow or Incomplete Data Updates​

Issue: "Data is outdated"​

Symptoms:

  • Cost data is several days behind
  • Real-time changes don't appear

Solutions:

  1. Check Sync Status

    • Go to Settings → Data Sync in CloudWise dashboard
    • Look for any error messages or failed sync attempts

  2. AWS API Limits

    • AWS Cost Explorer has rate limits
    • Large accounts may experience slower sync times

  3. Manual Refresh

    • Use the "Refresh Data" button in settings
    • Allow 2-4 hours for refresh to complete

4. Authentication Token Expiry​

Issue: "Session expired" or frequent re-authentication​

Symptoms:

  • Frequent login prompts
  • "Token expired" errors

Solutions:

  1. Role Session Duration

    # Check maximum session duration
    aws iam get-role --role-name CloudWise-Role
    • Increase maximum session duration to 12 hours if needed

  2. Clear Browser Cache

    • Clear cookies and cached data for CloudWise
    • Try using an incognito/private browsing window

Permission and Access Issues​

5. Insufficient Permissions​

Issue: "Access denied for specific features"​

Symptoms:

  • Some features are greyed out or inaccessible
  • Error: "Insufficient permissions to access this resource"

Solutions:

  1. Use the Built-in Troubleshoot Connection Tool

    CloudWise includes a Troubleshoot Connection tool that validates ALL permissions from your CloudFormation template automatically:

    • Go to Settings → AWS Accounts
    • Find your account card and click "Troubleshoot Connection"
    • The tool runs an IAM policy simulation (dry-run) against every permission in the template
    • Failed checks show exactly which actions are denied, grouped by policy SID

    The verification method depends on your template version:

    • Template v1.14.0+: Uses iam:SimulatePrincipalPolicy for comprehensive dry-run (tests all 139+ monitoring actions without invoking any API)
    • Older templates: Falls back to representative live API calls (one per category)

    If you see "Method: Live API calls", update your CloudFormation stack to the latest template for comprehensive validation.

  2. Review Required Permissions

    {
        "Required": [
            "ce:GetCostAndUsage",
            "ce:GetDimensionValues",
            "ce:GetReservationCoverage",
            "ce:GetReservationPurchaseRecommendation",
            "budgets:ViewBudget"
        ]
    }

  3. Update IAM Policy

6. Multi-Account Setup Issues​

Issue: "Can't see all accounts in organization"​

Symptoms:

  • Only master account data is visible
  • Member account costs are missing

Solutions:

  1. Consolidated Billing Setup

    • Ensure consolidated billing is enabled
    • Verify master account has access to member account billing

  2. Cross-Account Roles

    • Set up CloudWise IAM roles in each member account
    • Use identical permission policies across all accounts

Performance and Display Issues​

7. Dashboard Loading Problems​

Issue: "Dashboard is slow or unresponsive"​

Symptoms:

  • Pages take a long time to load
  • Graphs and charts don't appear

Solutions:

  1. Browser Compatibility

    • Use supported browsers: Chrome 90+, Firefox 88+, Safari 14+
    • Disable ad blockers that might interfere

  2. Clear Application Cache

    // Open browser developer tools and run:
    localStorage.clear();
    sessionStorage.clear();
    location.reload();

  3. Check Internet Connection

    • Ensure stable internet connection
    • Test with other cloud applications

8. Export and Report Issues​

Issue: "Can't export cost reports"​

Symptoms:

  • Export buttons don't work
  • Downloaded files are empty or corrupted

Solutions:

  1. Browser Settings

    • Allow pop-ups for cloudcostwise.io
    • Check download settings and permissions

  2. Data Size Limits

    • Large reports may timeout
    • Try exporting smaller date ranges
    • Use filters to reduce data size

API and Integration Issues​

9. API Authentication Problems (Coming Q1 2026)​

Note: API features are currently in development​

API access and webhooks are planned for Q1 2026 as part of our Enterprise Features release.

For current integration needs, please contact our support team at support@cloudcostwise.io

10. Notification and Alert Issues​

Issue: "Not receiving cost alerts"​

Symptoms:

  • Budget alerts aren't triggering
  • Email notifications not arriving

Solutions:

  1. Email Configuration

  2. Alert Thresholds

    • Review alert conditions and thresholds
    • Test with lower threshold values

Getting Additional Help​

Log Collection​

When contacting support, please provide:

  1. Browser Information

    Browser: Chrome 118.0.5993.88
    OS: macOS 14.0
    Screen Resolution: 1920x1080

  2. Error Messages

    • Screenshot of any error messages
    • Browser console errors (F12 → Console tab)

  3. Account Details

    • AWS account ID (last 4 digits only)
    • CloudWise account email
    • Approximate time when issue occurred

Self-Diagnostic Tools​

Health Check​

# Basic connectivity test
curl -I https://api.cloudcostwise.io/health

# AWS role assumption test
aws sts assume-role \
  --role-arn "arn:aws:iam::YOUR-ACCOUNT:role/CloudWise-Role" \
  --role-session-name "test-session" \
  --external-id "your-external-id"

Permission Validation​

# Test Cost Explorer access
aws ce get-cost-and-usage \
  --time-period Start=$(date -d "30 days ago" +%Y-%m-%d),End=$(date +%Y-%m-%d) \
  --granularity MONTHLY \
  --metrics BlendedCost

The fastest way to diagnose permission issues is the built-in Troubleshoot Connection tool:

  1. Navigate to Settings → AWS Accounts
  2. Click "Troubleshoot Connection" on any account card
  3. The tool automatically verifies all required permissions

What it checks:

  • Monitoring template (all tiers): AssumeRole, Cost Explorer, CUR bucket, Cost Reports, Compute Optimizer, EC2/Compute, S3/Storage, RDS/Databases, ELB/Networking, EMR/Analytics, CloudWatch/Management, Auto Scaling, ECR, Glue, Messaging, Integration, and more
  • Remediation template (Agentic+ tier): All write actions (EC2 stop/terminate, RDS stop, S3 lifecycle, Lambda right-size, etc.) are validated via dry-run — nothing is actually executed

How it works: The tool uses iam:SimulatePrincipalPolicy to test permissions without making real API calls. For remediation checks, it also passes the required session tag context (cloudwise-action: remediation) to accurately validate conditional policies.

If checks fail:

  • Expand any failed check to see the exact denied actions
  • The remediation message tells you which CloudFormation SID to update
  • Re-deploy or update your CloudFormation stack with the latest template

Contact Support​

If you can't resolve the issue using this guide:

Email Support: support@cloudcostwise.io

  • Include relevant error messages
  • Describe steps to reproduce the issue
  • Provide system information

Emergency Support: For critical issues affecting production environments

  • Mark email subject with "URGENT"
  • Include business impact description

Community Forum: github.com/cloudwise-app/cloudwise-community

  • Search existing solutions
  • Ask questions and share solutions

Documentation: docs.cloudcostwise.io

  • Complete setup guides
  • API documentation
  • Best practices

Response Times:

  • Standard support: 24-48 hours
  • Premium support: 4-8 hours
  • Emergency support: 1-2 hours