Appearance
Error Reference
This page lists all error codes returned by the Datascaphe Uplink Browser Extension, their causes, and recommended solutions.
Errors fall into two families:
0xerrors — Errors occuring while the server is processing information required for browser interaction (issue while getting scannerdata, error embedding the report...)1xerrors — Errors occuring during the authentication flow of the Browser Extension
Summary table
| Error code | Flow - HTTP code | Cause summary |
|---|---|---|
| 0x00 | Account config - 401 | Request not from authorized extension origin |
| 0x01 | Account config - 401 | Missing required POST fields |
| 0x021 | Account config - 401 | Missing or malformed Authorization header |
| 0x022 | Account config - 401 | JWT invalid or expired |
| 0x023 | Account config - 401 | JWT subject does not match user record |
| 0x04 | Account config - 200 | Unknown action parameter value |
| 0x05 | Account config - 200 | Unexpected token authentication result |
| 0x06 | Account config - 200 | No valid refresh token in token record |
| 0x07 | Account config - 200 | Unhandled server exception |
| 0x08 | Account config - 200 | No token record found; or Azure AD token refresh error |
| 0x09 | Account config - 403 | User not found / disabled; or embed token API error |
| 0x10 | Account config - 200 | No embed token returned by Power BI API |
| 1x01 | Browser Auth | Missing or empty login parameters |
| 1x02 | Browser Auth | User not found or disabled during OAuth flow |
| 1x03 | Browser Auth | OAuth provider returned an error |
| 1x04 | Browser Auth | Authorization code exchange failed |
| 1x05 | Browser Auth | OAuth state mismatch (CSRF check) |
| 1x07 | Browser Auth | Unhandled server exception during OAuth flow |
Server Processing Errors (0x)
Errors occuring while interacting with the extension or web pages.
Error 0x00 - Only accepts requests from extension
HTTP status: 401
Message: Only accepts requests from extension.
Cause: TThe server only accepts POST requests originating from the registered Datascaphe Uplink extension.
Recommended Actions:
- Ensure you are using the official Datascaphe Uplink browser extension.
- Do not attempt to call the hub endpoint directly from outside the extension.
Error 0x01 - Authentication information missing
HTTP status: 401
Message: Authentication information missing.
Cause: The request from the extension is missing one or more required fields: extension_code, account, or org_code.
Recommended Actions:
- Verify the extension is properly configured with a valid account and organization code (Dashboard → Organization).
- Re-open the extension options page and confirm all fields are filled in.
Error 0x021 - Missing or invalid Authorization header
HTTP status: 401
Message: Missing or invalid Authorization header.
Cause: Issue with the auth system between the extension and the server, the JWT is missing from the request.
Recommended Actions:
- Sign out and sign back in using the extension popup to obtain a fresh JWT.
- If the issue persists, clear the extension's local data and re-authenticate.
Error 0x022 - Invalid or expired token
HTTP status: 401
Message: Invalid or expired token.
Cause: Issue with the auth system between the extension and the server, the JWT may be malformed, signed with a different key, or past its expiry time.
Recommended Actions:
- Sign out and sign back in using the extension popup to obtain a new JWT.
- Check that your device's clock is accurate (clock skew can cause token validation failures).
Error 0x023 - User token mismatch
HTTP status: 401
Message: User token mismatch.
Cause: The sub (subject) claim in the JWT does not match the user ID found in the database for the provided account. This can happen if a token from a different user session is being replayed.
Recommended Actions:
- Sign out and sign back in using the extension popup.
- Ensure only one active session is running for this account.
Error 0x04 - Action specified is not available
Message: Action specified is not available
Cause: The action query parameter in the request URL contains a value that does not correspond to any implemented handler.
Recommended Actions:
- This error should not appear in normal extension usage. If it does, update the extension to the latest version.
Error 0x05 - Unexpected error
Message: Unexpected error
Cause: There was an issue while authenticating to the Power BI API, the report in Datascaphe backend may give more information on the exact error.
Recommended Actions:
- Sign out and sign back in using the extension popup.
- Verify that your user or Service Principal is allowed access to the Power BI workspace hosting the target report and that it has at least
buildpermission on the report. - If the issue persists, contact support with the approximate time of the error for log investigation.
Error 0x06 - Invalid value for refresh token
Message: tokenInfo empty or invalid value for refresh_token
Cause: The Power BI refresh token is missing, and no service principal is configured for this user. The server cannot obtain a new access token.
Recommended Actions:
- Sign out and sign back in using the extension popup to store a new refresh token.
- If using a service principal, verify it is correctly assigned to the report or user in the backend.
Error 0x07 - Server error
Message: Server error
Cause: An unhandled PHP exception occurred during request processing. This is a catch-all for unexpected server-side failures.
Recommended Actions:
- Retry the action. If the error persists, contact support with the time of occurrence for log investigation.
Error 0x08 - No refresh token
Message: please sign OUT then sign IN again using the extension popup.
Cause: No Power BI access token exists for this user, or the token record exists but has no refresh token and no service principal is assigned. The server cannot authenticate against the Power BI API.
Recommended Actions:
- Sign out then sign back in using the extension popup.
- If a service principal is configured, verify it is correctly assigned and active in the backend.
Error 0x08 - Azure AD token refresh failure
Message: <Azure AD error code>: <Azure AD error description>
Cause: The Azure AD token refresh request returned an error (other than an inactive-refresh-token expiry). Common causes include revoked credentials, misconfigured service principal, or tenant policy changes.
Recommended Actions:
- If the error mentions a revoked or invalid client secret, update the service principal's client secret in the Datascaphe backend.
- If the error mentions insufficient permissions, verify that the service principal has the required Power BI API permissions in Azure Entra ID.
- Sign out and sign back in to refresh credentials if the error is user-token related.
Error 0x09 - User validation failure
HTTP status: 403
Message: User not found or with invalid status, please check it matches the account you have registered.
Cause: The user was not found in the database, their account is disabled (Is Enabled = false), or the org_code in the request does not match the user's organization.
Recommended Actions:
- Verify that the account email and organization code configured in the extension match the values in the Datascaphe backend.
- Check in the backend that the user account is enabled (User Management → Is Enabled).
- Ensure the organization code in the extension options matches Dashboard → Organization.
Error 0x09 - Embed token failure
Message: Embed token: <Power BI error code>
Cause: The Power BI API returned an error when the hub requested an embed token using the service principal. Common causes: the workspace does not have Premium or Embedded capacity, or the service principal lacks access to the report or dataset.
Recommended Actions:
- Ensure the report is published in a workspace with Premium or Embedded capacity (required by Microsoft when using a service principal).
- Verify the service principal has the Contributor role or higher on the Power BI workspace.
- Check that the service principal is enabled in the Azure Entra ID tenant's Power BI admin settings (Tenant settings → Developer settings → Allow service principals to use Power BI APIs).
Error 0x10 - No Embed token in response
Message: No Embed token in response
Cause: The Power BI API responded successfully to the embed token request but the response did not contain a token field. This indicates an unexpected API response format.
Recommended Actions:
- Verify the Report ID and Dataset ID configured in the backend are correct and belong to the same workspace.
- Check the Power BI service status for any ongoing incidents.
- Contact support if the issue persists.
Authentication Errors (1x)
These errors occur during the OAuth login flow initiated by the browser extension.
Error 1x01
Message: Authentication information missing. Please check the options page.
Cause: The request is missing required parameters (account, or org_code), or they are present but hold empty/default values. This can happen if the extension options page was not fully configured before the login flow was triggered.
Recommended Actions:
- Open the extension options page and verify that the account email and organization code are correctly filled in.
- Sign out and attempt to sign in again.
Error 1x02
Message: User not found or with invalid status, please check the user and organization code match the ones you have registered.
Cause: During the OAuth login flow, the user could not be found in the database, their account is disabled, or the organization code does not match.
Recommended Actions:
- Verify that the account email and organization code in the extension options match the values registered in the Datascaphe backend.
- Check in the backend that the user account exists and is enabled (User Management → Is Enabled).
Error 1x03
Message: <OAuth error>: <OAuth error description>
Cause: The OAuth identity provider (Microsoft or Datascaphe) returned an error response during the authorization step. This can indicate a cancelled login, a denied consent, an expired authorization session, or a misconfigured OAuth application.
Recommended Actions:
- Retry signing in. If you cancelled the login dialog, try again and complete the authentication.
- If the error description mentions consent or permissions, ensure the Azure application has the required API permissions granted.
- If the error persists, check the Azure Entra ID application configuration for the Datascaphe tenant.
Error 1x04
Message: Authentication server error.
Cause: After the user authorized the login, the hub failed to exchange the authorization code for an access token. This can happen if the authorization code expired, if the redirect URI is misconfigured, or if the OAuth application credentials are invalid.
Recommended Actions:
- Retry signing in — authorization codes are single-use and expire quickly.
- If the error recurs, contact support as it may indicate a server-side configuration issue.
Error 1x05
Message: Authentication server error.
Cause: The state parameter returned by the OAuth provider does not match the value stored in the session. This is a security check that detects CSRF attacks or session mixups (e.g., multiple concurrent login attempts from the same browser).
Recommended Actions:
- Close any duplicate login tabs and retry signing in from a single browser tab.
- Clear the extension's local data, then sign in again.
- If using a shared or corporate browser with session isolation policies, try in a fresh browser profile.
Error 1x07
Message: Server error.
Cause: An unhandled PHP exception occurred during the OAuth GET flow processing. This is a catch-all for unexpected server-side failures.
Recommended Actions:
- Retry signing in. If the error persists, contact support with the time of occurrence for log investigation.