Common issues

This guide covers frequently encountered issues and their solutions.

Credentials not working

Verify IAM policies — The IAM user needs ce:GetCostAndUsage, ce:GetCostForecast, ec2:Describe*, rds:Describe*, cloudwatch:GetMetricData, and other read-only permissions. Use the AWS-managed ReadOnlyAccess and AWSBillingReadOnlyAccess policies as a starting point. (There is no AWS managed policy called CostExplorerReadOnly.)
Check for MFA requirements — If your AWS account enforces MFA, IAM access keys still work without MFA. However, if an IAM policy explicitly denies actions without MFA, the credentials will fail.
Verify the key is active — In the AWS Console, check that the access key status is Active under IAM > Users > Security Credentials.

Use the correct Object ID — Azure has three different Object IDs. You must use the Service Principal Object ID (found under Enterprise Applications), not the App Registration Object ID or the Application/Client ID.
Verify Cost Management Reader role — The Service Principal needs Cost Management Reader on the subscription to retrieve billing data.
Check secret expiry — Service Principal client secrets expire. If credentials suddenly stop working, the secret may have expired.

Enable required APIs — CLARITY checks 16 GCP APIs (4 required, 12 optional) when you add credentials. If validation fails, enable the listed APIs in the GCP Console under APIs & Services.
Verify service account roles — the service account needs BigQuery Data Viewer, BigQuery Job User, Compute Viewer, Monitoring Viewer and Billing Account Viewer at minimum. BigQuery Job User is easy to miss and without it every billing query fails, because reading the billing export requires running a query, not just reading a table.
Check BigQuery billing export — GCP billing data comes from BigQuery. The billing export must be enabled in the GCP Console under Billing > Export.

AWS Cost Explorer activation — If you just enabled Cost Explorer for the first time, it takes up to 24 hours before data becomes available.
GCP BigQuery billing export — BigQuery billing export must be enabled manually. After enabling, initial data backfill takes 24-48 hours.
Azure Cost Management access — If the Service Principal lacks Cost Management Reader, cost queries return a 403 error. Check the sync status for error details.
Check sync completed — Verify the sync status shows Completed (not In Progress or Failed).

First sync is the slowest — Initial discovery of all resources, metrics, and cost data may take 5-10 minutes depending on the number of resources.
Subsequent syncs are faster — After the first sync, only changed data is processed.
Large accounts — Accounts with thousands of resources take longer. This is normal.
Rate limits — Cloud provider APIs have rate limits. CLARITY handles throttling automatically with retries.

Verify credentials are active — Check that your credentials show a green status badge on the accounts page
Check the date range — If it is early in the month (before day 7), CLARITY defaults to "Last 30 Days" to ensure data is visible
Wait for sync — Cost data only appears after a successful sync. Check the sync status indicator
Check provider selection — Ensure the correct cloud provider is selected in the dashboard header

TIP

If you just added credentials, wait for the first sync to complete before checking the dashboard. The sync status is visible in the header bar.

Check with your operator that AI_PROVIDER is set — this is the usual cause. AI is included in every paid tier, but it is off by default at the deployment level and no tier upgrade will turn it on. The fastest test is to click Explain on any finding: if AI is not configured it returns "AI provider not configured".
Use a manual sync — scheduled background syncs do not run batch validation, so badges only refresh when you sync by hand.
Look for badges — after a manual sync, recommendations and insights should display Agree, Modify, or Disagree badges. A finding with no badge was not ranked by the model; it does not mean the AI disagreed.

See AI Analysis for details on how AI works in CLARITY.