Skip to main content

Troubleshooting

The UI shows no backend or service version​

The backend or the service is unreachable. Setup → About shows the three versions; a blank one is the component to look at. Sign-in tokens may have expired: sign out and back in. If the versions stay blank, contact Datawareness support, who can see the Container Apps in the managed resource group.

Test email fails​

Microsoft 365. The message names the cause, and the causes need different fixes:

  • "Exchange refused the send as that mailbox" — the setup in Email for notifications is incomplete. Either the identity has no Mail.Send at all, or what it has does not cover this mailbox. Test-ServicePrincipalAuthorization -Identity <client ID> -Resource <mailbox> answers it on Path A, Test-ApplicationAccessPolicy on Path B.
  • "Microsoft Graph rejected this deployment's identity" — the token itself was refused. On Path B the Mail.Send app role assignment has been removed; re-grant it. On Path A there is no app role assignment to lose, so look at the identity instead — it has been deleted, or the deployment is running without one.
  • "no Exchange Online mailbox" — the address is unlicensed, or is a group or distribution list rather than a mailbox.
  • "No mailbox with that address exists in this tenant" — check the spelling.
  • "no managed identity" — the backend is running somewhere without an identity assigned, so Microsoft 365 email is unavailable. Use an SMTP relay instead.

Exchange caches an application's permissions for 30 minutes to 2 hours, so a test sent immediately after a change may still fail with the same 403. See the end of Email for notifications.

SMTP. Check host, port, and secure (TLS-direct vs STARTTLS). Many relays require an authenticated From address on the same domain as smtp_username. If your mail host is Office 365 and MFA is enforced, SMTP cannot work at all — use Microsoft 365 instead.

Loads stay "queued"​

The service is not running. Setup → About shows its version; blank means unreachable. Contact Datawareness support, who can restart it. Loads that were running when the service stopped are queued again when it comes back.

401 / 403 on the external API​

  • Token audience mismatch — the JWT was minted for the wrong client ID. Check Setup → About → Backend Client ID and align the caller.
  • Scope missing — the user has no role on the app registration. Add them in Microsoft Entra ID.

On the Data API (/api/data):

  • 403 "The Data API is not enabled" — no Cloud Connector Data client ID under Setup → Access.
  • 403 "Cloud Connector sign-in tokens are not accepted" — the caller used a Cloud Connector token. Use one issued for the Cloud Connector Data app.
  • 403 "Not found or access denied" — no enabled role in that environment both covers the dataset and names the caller, or the dataset does not exist. Both look the same on purpose.
  • Power BI: "this credential type isn't supported for this resource" — either the Data API is still off (no client ID under Setup → Access), or the credential is set on the bare host. Set it on the Cloud Connector Data base URL, https://<backend host>/api/data.
  • Power BI: AADSTS500011 (resource principal not found) — the Cloud Connector Data app has no Application ID URI equal to https://<backend host>.
  • The Members search finds apps but no users — User.Read.All is not consented on the Cloud Connector registration (User.ReadBasic.All is not enough for an app without a signed-in user). Groups need GroupMember.Read.All. A permission consented a moment ago is picked up on the next search.
  • A group in a role lets nobody in — GroupMember.Read.All is not consented on the Cloud Connector registration. The backend log shows [data-api] group membership check failed.

A load ends with status "warning"​

The rows are loaded; something after the load went wrong. Open the load in the Dataset log:

  • "Data loaded successfully but export sync failed" — the export to a destination failed. The export-sync row has the error; the next export catches up from the last success.
  • "Duplicate business key detected" — a full load met the same key twice, so later rows overwrote earlier ones. The business key is incomplete.
  • "Nested dataset(s) did not load cleanly" — open the nested dataset's own load.

A load is stuck, or shows "running" after a restart​

A cloud load that reports no progress for 90 minutes is failed automatically; a Gateway job after the On-prem job stall limit. After a service restart, loads that were running are queued again. If loads stay queued and nothing runs, the service is down: check Setup → About and contact support.

Works in Preview, fails in the job​

  • A Preview is one request with no paging, no token cache and the instance you picked. A job loads every enabled instance and follows paging, so look at the failing instance and page in the Dataset log's endpoint URLs.
  • A job, schedule or trigger URL skips a disabled source system, instance or dataset; a person's Refresh now does not.
  • {{system:lastLoadedAt}} resolves in the URL path only; in a header, parameter or body it is sent as literal text.
  • A data-reference or integer-loop variable works in the URL path and (integer loop) query parameters only.

Source endpoint returns 429​

Turn on Run loads one at a time per instance on the source system's Configurations tab, or lower Max parallel on the job's dataset-refresh activity. Every 429 is already retried with the server's Retry-After.

The Connect… popup is blank or returns no refresh token​

A blank popup means the API URL followed by /api/auth/oauth/callback is missing under the Web platform of the Cloud Connector app registration (see After deployment: activation and redirect URIs). "Token exchange returned no refresh_token" means the registration lacks the delegated permissions the scope asks for, or admin consent.

SQL export fails with a certificate error​

A SQL Server on an internal VM or on-premises host with a self-signed certificate is refused by the driver. Turn on Trust server certificate on the export system; encryption stays on.

Export to an on-premises SQL Server fails to connect​

An error that mentions the handshake before login (ODBC 08001) means the relay tunnel between the deployment and your network is down: check that the on-premises relay process is running. A login timeout (HYT00) means the tunnel is slow but alive; stored-procedure steps retry the connection on their own.

Outbound database call times out​

Likely a firewall rule. Re-run the script from Setup → Access → Cloud Connector external IP on the destination; without a NAT Gateway the IP can change.

A Power BI refresh action never completes​

The action polls up to Max attempts × Interval, 10 minutes by default; a long refresh needs more attempts. Check the model's refresh history in the Power BI service; a refresh the service reports as failed ends the action as failed with Power BI's message.

The secret-expiry email mentions "Reload credentials"​

That button belonged to an earlier version. Rotate the secret as described in Rotating a client secret.