Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Test Connection returns 401 with no further detail. | Almost always a value swapped between your own app registration and Equerra's, as described in Entra App Registration: your own Client ID or Secret used where Equerra's Scope was needed (or the other way round), or the Token Endpoint URL built with Equerra's tenant ID instead of your own. | Re-check each field against which app registration it actually belongs to. |
| Test Connection returns 401, and you are testing a non-production Elevate environment. | Admin consent for the connector role was granted against a different environment's Equerra app registration than the one you are pointed at. | Grant the Application permission and admin consent against the correct environment's Equerra app registration. |
Test Connection or Diagnose Auth returns 401 invalid_token, and every field matches what it should hold. | Your own app registration (not Equerra's) never had the connector's Application permission added at all, not just un-consented. This is easy to miss because it does not produce the 403 you would expect for a missing role; it comes back as the same generic 401 invalid_token as a mismatched Client ID, Secret or Scope, since Entra cannot correctly scope a token to a resource your app has no permission entry for at all. Verified by testing. | On your own app registration (not Equerra's), add the Application permission for Equerra Elevate API, tick the connector role, and grant admin consent again in full. If Test Connection still fails immediately afterward, do not assume the fix did not work: Entra permission and consent changes can take anywhere from a couple of minutes to over an hour to propagate before token issuance reflects them. Wait a few minutes and retry before troubleshooting further. |
Test Connection returns 403 with APP_ROLE_MISSING. | The token is valid and correctly formed, but the connector role is missing. | Confirm the role was added and admin consent granted, against the right environment. |
Push This Entity returns 500 with TENANT_CONN_MISSING. | The portal recognises the tenant but it has no per-tenant database connection yet. | Contact Equerra Support; a platform administrator needs to finish provisioning. |
| Records pushed but portal users see only raw fields. | Field Configuration was never synced. | Choose Sync Field Configuration on the Setup page. |
| Vendor write-back fails with "Dimension code is required". | BC requires a default dimension that the portal form did not collect. | Add the dimension as a portal-side field, or add it to default dimensions on the vendor template. Then Retry the Request Log row. |
| Approved request never reaches BC. | The Job Queue is not running, or Process Approvals has not been triggered. | Check the Job Queue Entry; trigger it manually from the Setup page to confirm. |
| Watermark seems wrong (records you expect are not pushed). | Records were modified at exactly the same timestamp as the watermark and the comparison is exclusive. | Use Force Full Resync for that entity. |
Support
For installation issues or app-role problems, contact Equerra Support at the address on your service agreement. The fastest way to get help is to attach:
- The Endpoint Code being used (not the secret).
- A screenshot of the failing action.
- The HTTP status returned by Test Connection.