Troubleshooting

Sync issues

A sync is stuck in “running” state

A sync may appear stuck if it is processing a large number of resources, or if the underlying process has stalled.

Check the Sync Runs page for any error details in the run log.
If the sync has been running longer than expected with no progress, try cancelling it and running it again.
For large cloud accounts, the first sync can take significantly longer than subsequent ones. Allow extra time before concluding something is wrong.

A sync failed

Open the sync run from Data Pipelines → Integrations and expand the failed run to see the error message.

Common causes:

Error	Likely cause	Fix
`permission denied` / `403`	Integration credentials lack required permissions	Review the IAM role or service account permissions for your provider
`credentials expired` / `401`	Credentials have rotated or expired	Re-enter credentials in the integration settings
`connection timeout`	Network connectivity issue between the platform and the cloud provider	Check for outbound network restrictions; retry the sync
`quota exceeded`	Cloud provider API rate limit hit	Reduce the number of tables being synced, or schedule syncs less frequently

For provider-specific permission requirements, see the relevant Integration Guide.

Resources are missing from the Asset Inventory after a sync completes

Confirm the sync completed without errors. Partial failures may result in some tables being skipped.
Check that the integration is scoped to the correct accounts and regions. Resources in accounts or regions not covered by the integration will not appear.
Some resource types may not be included in your integration’s table selection. Review the table configuration in the integration settings.
The Asset Inventory reflects the most recent completed sync. If you are expecting newly created resources, run a fresh sync.

Policy issues

A policy is not showing any violations

Verify the policy query returns results when run manually in the SQL Console. If the query returns no rows, there are no violations — which may be correct.
Check that the tables referenced in the query have been synced. If the integration doesn’t include those tables, the query will return empty results.
Confirm the sync has run recently. Policies evaluate against the latest synced data; stale data may not reflect current infrastructure state.

A policy is showing unexpected violations

Run the policy query directly in the SQL Console to inspect the results.
Check whether the policy scope is set to a saved filter that is broader or narrower than intended.
Verify the query logic. Policies return one row per violation, so a query that inadvertently joins tables or doesn’t filter correctly may return duplicate or incorrect results.

API issues

API requests return `401 Unauthorized`

Confirm you are passing the API key in the Authorization header as Bearer <YOUR_API_KEY>.
Check that the API key has not been revoked. See API Keys.
Ensure you are using a Platform API key, not a CloudQuery Cloud API key. These are different and not interchangeable. See Platform API.

API requests return `403 Forbidden`

The API key role does not have permission for the requested operation.

general:read and general:write keys cannot access user management, SSO configuration, or admin endpoints.
admin:read keys have read-only access to admin resources and cannot create or modify anything.
ci keys are scoped to CI/CD operations and cannot access admin or user management endpoints.

Create a new key with the appropriate role from Organization Settings → API Keys. See API Keys for the full role reference.

API requests return `404 Not Found`

Double-check the endpoint path and any path parameters (team name, sync ID, etc.).
Confirm you are using the correct base URL for your deployment: https://<YOUR_PLATFORM_URL>/api.

SSO issues

Users can’t log in after SSO is configured

Verify the SAML metadata URL or XML is correct and up to date in the SSO configuration.
Confirm that the identity provider’s assertion consumer service (ACS) URL matches what is configured in CloudQuery Platform.
Check that the NameID format in your IdP matches the expected format (typically email address).
For group-based role mapping, confirm the group attribute name matches what your IdP sends in the SAML assertion.

See Enabling Single Sign-On for full configuration details.

SSO is configured but users are not getting the right roles

Review the group-to-role mapping in Organization Settings → SSO.
Confirm that your identity provider is sending the expected group claims in the SAML assertion.
Users receive the role mapped to their group at login time. Changes to mapping take effect on next login.

See Map Groups to Roles for setup details.

Getting more help

If you can’t resolve an issue using this guide:

Community Forum: community.cloudquery.io — browse existing threads or post a question
GitHub Issues: github.com/cloudquery/cloudquery — report bugs or check known issues
Getting Help: Getting Help — full list of support resources