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:

Check IAM Role Permissions

# Verify the CloudWise role's policy (use the role name at the end of the CloudWiseRoleArn in your stack's Outputs:
# CloudWise-Cost-Monitoring-Role for a manual setup, CloudWise-Cost-Monitoring-Role-<id> for a one-click setup)
aws iam get-role-policy --role-name CloudWise-Cost-Monitoring-Role --policy-name CloudWise-Cost-Monitoring-Policy

Validate External ID
- One-click setup passes the External ID into the stack for you. For a manual stack, the ExternalId parameter must be the value the app showed for that AWS account; CloudWise refuses the template's default. Update the stack with the right value and connect again
- If you edited the trust policy by hand, undo the edit. If you cannot, run one-click setup again for the same AWS account from Settings → AWS Accounts: it creates a fresh stack, checks that CloudWise can use the new role and read its cost reports (the same checks as a first connection), and only then points the existing account in CloudWise at it. If the new role does not work yet, the account keeps its old role and the connect screen says why; wait a minute and run it again. If you are already at your plan's account limit, you see an upgrade prompt instead of the one-click button; in that case remove the account under Settings → AWS Accounts first, then connect it again. Removing an account deletes its findings and daily cost history in CloudWise; the next scan rebuilds the findings. Either way CloudWise no longer uses the old stack, and you can delete it in CloudFormation. The delete removes the old role, its policy and the cost report definition (or data export), then stops with DELETE_FAILED on the cost-report bucket if the bucket is not empty. With the default report format the bucket is never empty, because AWS writes a test file to it when the report is created. To finish, empty the bucket in S3, including every object version, then delete the stack again
Verify Role ARN
- Double-check the role ARN format: arn:aws:iam::YOUR-ACCOUNT-ID:role/CloudWise-Cost-Monitoring-Role (manual setup) or ...Role-<id> (one-click setup). Copy it from your stack's CloudWiseRoleArn output
- Ensure there are no extra spaces or characters

Issue: "Role assumption failed"

Symptoms:

Setup completes but data doesn't load
The account card under Settings → AWS Accounts says "Last scan failed", with "AWS refused the CloudWise role" as the reason

Solutions:

Trust Policy Configuration

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

Check the principal
- The template fills in CloudWise's account and role for you; don't replace them by hand
- Contact support if you changed the trust policy and are unsure what it should say

2. Missing Cost Data

Issue: "No cost data available"

Symptoms:

Dashboard shows empty or incomplete data
An empty Overview usually means the first scan or the first Cost and Usage Report has not arrived yet; check the account card under Settings → AWS Accounts for "Last scan failed" or "Last scan missed some Regions"

Solutions:

Wait for Initial Sync
- Waste findings come from the first scan; cost data follows once AWS delivers your Cost and Usage Report
- For a brand-new Cost and Usage Report, AWS can take up to 24 hours to deliver the first one

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

Billing Permissions
- Run Troubleshoot Connection (Settings → AWS Accounts) to see any denied cost action
- Check that Cost Explorer is enabled in your AWS account

Issue: "Partial cost data missing"

Symptoms:

Some services or regions show no data
Inconsistent cost information

Solutions:

Service-Specific Permissions
- If the account card says "Role update needed", update the stack to the latest template
Regional Data Issues
- 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.
  - A region you haven't enabled is skipped, and when CloudWise can tell that's the reason it doesn't show a notice, because leaving it off is your choice. To get coverage there, enable it in the AWS Console (Account → AWS Regions). Findings from before you turned it off stay listed for up to 7 days.
  - A region that fails for another reason is not skipped quietly. If the rest of the scan finished, the account card shows "Last scan missed some Regions" with a short line such as "Couldn't scan me-south-1 (AWS refused the CloudWise role)". CloudWise tries it again on the next scan.
  - A region you have enabled but CloudWise can't reach is skipped too, and you'll see it on the account card under Settings → AWS Accounts and in the workspace Findings view. After one missed scan the card says "Not scanned on the last scan: me-south-1", and CloudWise tries again on the next scan. If it keeps happening, the card says "Still can't reach me-south-1: 2 scans in a row". Check that the region is available and that your CloudWise role can be used there. Findings CloudWise already had stay listed for up to 7 days, and the daily trend may dip until the region is scanned again.
  - If your CloudWise role template is older than 1.34.0, CloudWise can't tell these two cases apart, so an unreachable region is treated as one you haven't enabled. Update the role to see the notice.

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:

Check the account card
- Go to Settings → AWS Accounts; a failed scan is shown on the account card
- Run Troubleshoot Connection if the card shows an error
AWS delivery lag
- AWS cost data itself arrives with a lag of a day or more, so the newest day is rarely complete
- AWS Cost Explorer also has rate limits

4. Authentication Token Expiry

Issue: "Session expired" or frequent re-authentication

Symptoms:

Frequent login prompts

Solutions:

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:

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 a dry run of every monitoring action in the template, without invoking any of them
- 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.
Update the stack
- Add missing permissions to your CloudWise IAM role
- The easiest fix is to update the stack to the latest template; see the IAM Best Practices Guide

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:

Connect each account
- CloudWise covers the accounts you connect, one Connect flow per account
- Free covers 1 account; Shield and Agentic cover up to 5. Compliance connects none by design: it works from Air-Gapped uploads
Service Control Policies
- Make sure no SCP blocks sts:AssumeRole on the CloudWise role or the read-only actions it uses

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:

Browser Compatibility
- Use supported browsers: Chrome 90+, Firefox 88+, Safari 14+

Clear Application Cache

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

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:

Browser Settings
- If the Export button is unavailable or asks you to upgrade, export is a Shield-and-above feature
- Otherwise check your browser's download settings and permissions
Data Size Limits
- Large reports may timeout
- Try exporting smaller date ranges
- Use filters to reduce data size

API and Integration Issues

9. API Key Problems

There is no general public API. Shield and above can create API keys in Settings → API Keys for the Prometheus metrics endpoint. If a scrape returns 401 or 403, check that the key is still active and that your plan is Shield or above. See Prometheus Integration.

10. Notification and Alert Issues

Issue: "Not receiving cost alerts"

Symptoms:

Budget alerts aren't triggering
Email notifications not arriving

Solutions:

Email Configuration
- Check spam/junk folders
- Open Settings → Budget Alerts and check the Notification email on the alert; budget alerts are sent to that address
- Add noreply@cloudcostwise.io to safe senders
Alert Thresholds
- Review alert conditions and thresholds
- Test with lower threshold values

Getting Additional Help

Log Collection

When contacting support, please provide:

Browser Information

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

Error Messages
- Screenshot of any error messages
- Browser console errors (F12 → Console tab)
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

Permission Validation

# Test Cost Explorer access (use a recent date range)
aws ce get-cost-and-usage \
  --time-period Start=YYYY-MM-DD,End=YYYY-MM-DD \
  --granularity MONTHLY \
  --metrics BlendedCost

Troubleshoot Connection (Recommended)

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

Navigate to Settings → AWS Accounts
Click "Troubleshoot Connection" on any account card
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

Include business impact description

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

Search existing solutions
Ask questions and share solutions

Documentation: docs.cloudcostwise.io

Setup guides
Best practices

Common Setup Issues​

1. AWS Account Connection Problems​

Issue: "Unable to connect to AWS account"​

Issue: "Role assumption failed"​

2. Missing Cost Data​

Issue: "No cost data available"​

Issue: "Partial cost data missing"​

Data Synchronization Issues​

3. Slow or Incomplete Data Updates​

Issue: "Data is outdated"​

4. Authentication Token Expiry​

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

Permission and Access Issues​

5. Insufficient Permissions​

Issue: "Access denied for specific features"​

6. Multi-Account Setup Issues​

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

Performance and Display Issues​

7. Dashboard Loading Problems​

Issue: "Dashboard is slow or unresponsive"​

8. Export and Report Issues​

Issue: "Can't export cost reports"​

API and Integration Issues​

9. API Key Problems​

10. Notification and Alert Issues​

Issue: "Not receiving cost alerts"​

Getting Additional Help​

Log Collection​

Self-Diagnostic Tools​

Health Check​

Permission Validation​

Troubleshoot Connection (Recommended)​

Contact Support​

Common Setup Issues

1. AWS Account Connection Problems

Issue: "Unable to connect to AWS account"

Issue: "Role assumption failed"

2. Missing Cost Data

Issue: "No cost data available"

Issue: "Partial cost data missing"

Data Synchronization Issues

3. Slow or Incomplete Data Updates

Issue: "Data is outdated"

4. Authentication Token Expiry

Issue: "Session expired" or frequent re-authentication

Permission and Access Issues

5. Insufficient Permissions

Issue: "Access denied for specific features"

6. Multi-Account Setup Issues

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

Performance and Display Issues

7. Dashboard Loading Problems

Issue: "Dashboard is slow or unresponsive"

8. Export and Report Issues

Issue: "Can't export cost reports"

API and Integration Issues

9. API Key Problems

10. Notification and Alert Issues

Issue: "Not receiving cost alerts"

Getting Additional Help

Log Collection

Self-Diagnostic Tools

Health Check

Permission Validation

Troubleshoot Connection (Recommended)

Contact Support